@furystack/shades-common-components 13.5.0 → 15.0.0

package/src/components/linear-progress.spec.tsx

@@ -1,10 +1,18 @@
 import { Injector } from '@furystack/inject'
-import { createComponent, initializeShadeRoot } from '@furystack/shades'
+import { createComponent, initializeShadeRoot, Shade } from '@furystack/shades'
 import { ObservableValue, sleepAsync, usingAsync } from '@furystack/utils'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { ThemeProviderService } from '../services/theme-provider-service.js'
 import { LinearProgress } from './linear-progress.js'
 
+const ProgressWrapper = Shade<{ obs: ObservableValue<number> }>({
+  customElementName: 'test-linear-progress-wrapper',
+  render: ({ props, useObservable }) => {
+    const [value] = useObservable('value', props.obs)
+    return <LinearProgress variant="determinate" value={value} />
+  },
+})
+
 describe('LinearProgress', () => {
   let originalAnimate: typeof Element.prototype.animate
 
@@ -35,7 +43,7 @@ describe('LinearProgress', () => {
     vi.restoreAllMocks()
   })
 
-  it('should render with shadow DOM', async () => {
+  it('should render as custom element', async () => {
     await usingAsync(new Injector(), async (injector) => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
@@ -90,12 +98,11 @@ describe('LinearProgress', () => {
     it('should set aria-valuenow for determinate variant', async () => {
       await usingAsync(new Injector(), async (injector) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
-        const value = new ObservableValue(50)
 
         initializeShadeRoot({
           injector,
           rootElement,
-          jsxElement: <LinearProgress variant="determinate" value={value} />,
+          jsxElement: <LinearProgress variant="determinate" value={50} />,
         })
 
         await sleepAsync(50)
@@ -110,12 +117,11 @@ describe('LinearProgress', () => {
     it('should set bar width based on value', async () => {
       await usingAsync(new Injector(), async (injector) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
-        const value = new ObservableValue(75)
 
         initializeShadeRoot({
           injector,
           rootElement,
-          jsxElement: <LinearProgress variant="determinate" value={value} />,
+          jsxElement: <LinearProgress variant="determinate" value={75} />,
         })
 
         await sleepAsync(50)
@@ -128,12 +134,11 @@ describe('LinearProgress', () => {
     it('should clamp value to 0-100 range', async () => {
       await usingAsync(new Injector(), async (injector) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
-        const value = new ObservableValue(150)
 
         initializeShadeRoot({
           injector,
           rootElement,
-          jsxElement: <LinearProgress variant="determinate" value={value} />,
+          jsxElement: <LinearProgress variant="determinate" value={150} />,
         })
 
         await sleepAsync(50)
@@ -146,12 +151,11 @@ describe('LinearProgress', () => {
     it('should clamp negative values to 0', async () => {
       await usingAsync(new Injector(), async (injector) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
-        const value = new ObservableValue(-20)
 
         initializeShadeRoot({
           injector,
           rootElement,
-          jsxElement: <LinearProgress variant="determinate" value={value} />,
+          jsxElement: <LinearProgress variant="determinate" value={-20} />,
         })
 
         await sleepAsync(50)
@@ -161,15 +165,15 @@ describe('LinearProgress', () => {
       })
     })
 
-    it('should update bar width when observable value changes', async () => {
+    it('should update bar width when value prop changes', async () => {
       await usingAsync(new Injector(), async (injector) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
-        const value = new ObservableValue(20)
+        const obs = new ObservableValue(20)
 
         initializeShadeRoot({
           injector,
           rootElement,
-          jsxElement: <LinearProgress variant="determinate" value={value} />,
+          jsxElement: <ProgressWrapper obs={obs} />,
         })
 
         await sleepAsync(50)
@@ -177,22 +181,22 @@ describe('LinearProgress', () => {
         const bar = document.querySelector('shade-linear-progress .progress-bar') as HTMLElement
         expect(bar.style.width).toBe('20%')
 
-        value.setValue(80)
+        obs.setValue(80)
         await sleepAsync(50)
 
         expect(bar.style.width).toBe('80%')
       })
     })
 
-    it('should update aria-valuenow when observable value changes', async () => {
+    it('should update aria-valuenow when value prop changes', async () => {
       await usingAsync(new Injector(), async (injector) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
-        const value = new ObservableValue(30)
+        const obs = new ObservableValue(30)
 
         initializeShadeRoot({
           injector,
           rootElement,
-          jsxElement: <LinearProgress variant="determinate" value={value} />,
+          jsxElement: <ProgressWrapper obs={obs} />,
         })
 
         await sleepAsync(50)
@@ -200,7 +204,7 @@ describe('LinearProgress', () => {
         const el = document.querySelector('shade-linear-progress') as HTMLElement
         expect(el.getAttribute('aria-valuenow')).toBe('30')
 
-        value.setValue(90)
+        obs.setValue(90)
         await sleepAsync(50)
 
         expect(el.getAttribute('aria-valuenow')).toBe('90')

package/src/components/linear-progress.tsx

@@ -1,5 +1,4 @@
 import { Shade, createComponent } from '@furystack/shades'
-import type { ObservableValue } from '@furystack/utils'
 import { buildTransition, cssVariableTheme } from '../services/css-variable-theme.js'
 import type { Palette } from '../services/theme-provider-service.js'
 import { ThemeProviderService } from '../services/theme-provider-service.js'
@@ -7,10 +6,9 @@ import { promisifyAnimation } from '../utils/promisify-animation.js'
 
 export type LinearProgressProps = {
   /**
-   * An observable progress value (0–100). Used when variant is 'determinate'.
-   * The component subscribes internally and updates the bar without re-rendering.
+   * A progress value (0–100). Used when variant is 'determinate'.
    */
-  value?: ObservableValue<number>
+  value?: number
   /**
    * The variant of the progress indicator.
    * - 'determinate': shows a fixed progress bar based on `value`
@@ -33,7 +31,7 @@ export type LinearProgressProps = {
 const clampValue = (v: number) => Math.max(0, Math.min(100, v))
 
 export const LinearProgress = Shade<LinearProgressProps>({
-  shadowDomName: 'shade-linear-progress',
+  customElementName: 'shade-linear-progress',
   css: {
     display: 'block',
     fontFamily: cssVariableTheme.typography.fontFamily,
@@ -68,15 +66,11 @@ export const LinearProgress = Shade<LinearProgressProps>({
       transition: 'none',
     },
   },
-  render: ({ props, injector, useObservable, useHostProps, useRef }) => {
+  render: ({ props, injector, useHostProps, useRef }) => {
     const themeProvider = injector.getInstance(ThemeProviderService)
     const barRef = useRef<HTMLElement>('progressBar')
     const variant = props.variant || 'indeterminate'
-
-    if (variant === 'determinate' && props.value) {
-      useObservable('progressValue', props.value)
-    }
-    const value = clampValue(props.value?.getValue() ?? 0)
+    const value = clampValue(props.value ?? 0)
 
     const color = themeProvider.theme.palette[props.color || 'primary'].main
     useHostProps({

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

@@ -14,7 +14,7 @@ export type ListItemProps<T> = {
 }
 
 export const ListItem: <T>(props: ListItemProps<T>, children: ChildrenList) => JSX.Element<any> = Shade({
-  shadowDomName: 'shade-list-item',
+  customElementName: 'shade-list-item',
   css: {
     display: 'flex',
     fontFamily: cssVariableTheme.typography.fontFamily,
@@ -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,10 +32,17 @@ 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({
-  shadowDomName: 'shade-list',
+  customElementName: 'shade-list',
   css: {
     display: 'block',
     fontFamily: cssVariableTheme.typography.fontFamily,
@@ -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) => (

package/src/components/loader.spec.tsx

@@ -40,7 +40,7 @@ describe('Loader', () => {
     vi.restoreAllMocks()
   })
 
-  it('should render with shadow DOM', async () => {
+  it('should render as custom element', async () => {
     await usingAsync(new Injector(), async (injector) => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 

package/src/components/loader.tsx

@@ -25,7 +25,7 @@ interface LoaderProps {
 }
 
 export const Loader = Shade<LoaderProps>({
-  shadowDomName: 'shade-loader',
+  customElementName: 'shade-loader',
   css: {
     display: 'inline-block',
     fontFamily: cssVariableTheme.typography.fontFamily,