@furystack/shades-common-components 13.5.0 → 15.0.0

package/src/components/markdown/markdown-display.spec.tsx

@@ -14,7 +14,7 @@ describe('MarkdownDisplay', () => {
     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
 
@@ -240,4 +240,136 @@ describe('MarkdownDisplay', () => {
       expect(root?.children.length).toBe(0)
     })
   })
+
+  describe('keyboard navigation', () => {
+    it('should make links focusable', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <MarkdownDisplay content="[Link A](https://a.com) and [Link B](https://b.com)" />,
+        })
+
+        await flushUpdates()
+
+        const links = document.querySelectorAll<HTMLAnchorElement>('shade-markdown-display .md-link')
+        expect(links.length).toBe(2)
+
+        links[0].focus()
+        expect(document.activeElement).toBe(links[0])
+
+        links[1].focus()
+        expect(document.activeElement).toBe(links[1])
+      })
+    })
+
+    it('should make code blocks focusable via tabIndex', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <MarkdownDisplay content={'```js\nconsole.log("hi")\n```'} />,
+        })
+
+        await flushUpdates()
+
+        const codeBlock = document.querySelector('shade-markdown-display .md-code-block') as HTMLPreElement
+        expect(codeBlock).not.toBeNull()
+        expect(codeBlock.tabIndex).toBe(0)
+
+        codeBlock.focus()
+        expect(document.activeElement).toBe(codeBlock)
+      })
+    })
+
+    it('should make checkbox inputs focusable when not disabled', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <MarkdownDisplay content={'- [ ] Task A\n- [ ] Task B'} readOnly={false} onChange={() => {}} />,
+        })
+
+        await flushUpdates()
+
+        const checkboxes = document.querySelectorAll<HTMLInputElement>(
+          'shade-markdown-display shade-checkbox input[type="checkbox"]',
+        )
+        expect(checkboxes.length).toBe(2)
+
+        checkboxes[0].focus()
+        expect(document.activeElement).toBe(checkboxes[0])
+        expect(checkboxes[0].disabled).toBe(false)
+      })
+    })
+
+    it('should toggle checkbox via keyboard activation', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const onChange = vi.fn()
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <MarkdownDisplay content="- [ ] My Task" readOnly={false} onChange={onChange} />,
+        })
+
+        await flushUpdates()
+
+        const input = document.querySelector(
+          'shade-markdown-display shade-checkbox input[type="checkbox"]',
+        ) as HTMLInputElement
+        expect(input).not.toBeNull()
+
+        input.focus()
+        expect(document.activeElement).toBe(input)
+
+        input.click()
+        await flushUpdates()
+
+        expect(onChange).toHaveBeenCalledOnce()
+        expect(onChange).toHaveBeenCalledWith('- [x] My Task')
+      })
+    })
+
+    it('should have correct focus order for mixed interactive elements', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        const content = [
+          '[First link](https://first.com)',
+          '',
+          '```js',
+          'code()',
+          '```',
+          '',
+          '[Second link](https://second.com)',
+        ].join('\n')
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <MarkdownDisplay content={content} />,
+        })
+
+        await flushUpdates()
+
+        const focusableElements = document.querySelectorAll(
+          'shade-markdown-display a[href], shade-markdown-display [tabindex="0"]',
+        )
+        expect(focusableElements.length).toBe(3)
+
+        const [firstLink, codeBlock, secondLink] = focusableElements
+        expect(firstLink.tagName).toBe('A')
+        expect(codeBlock.tagName).toBe('PRE')
+        expect(secondLink.tagName).toBe('A')
+      })
+    })
+  })
 })

package/src/components/markdown/markdown-display.tsx

@@ -60,7 +60,7 @@ const renderBlock = (
       return <Typography variant="body1">{renderInline(node.children)}</Typography>
     case 'codeBlock':
       return (
-        <pre className="md-code-block" data-language={node.language || undefined}>
+        <pre className="md-code-block" data-language={node.language || undefined} tabIndex={0}>
           <code>{node.content}</code>
         </pre>
       )
@@ -105,7 +105,7 @@ const renderBlock = (
  * blockquotes, images, links, and horizontal rules.
  */
 export const MarkdownDisplay = Shade<MarkdownDisplayProps>({
-  shadowDomName: 'shade-markdown-display',
+  customElementName: 'shade-markdown-display',
   css: {
     display: 'block',
     fontFamily: cssVariableTheme.typography.fontFamily,
@@ -136,6 +136,11 @@ export const MarkdownDisplay = Shade<MarkdownDisplayProps>({
       whiteSpace: 'pre',
     },
 
+    '& .md-code-block:focus-visible': {
+      outline: cssVariableTheme.action.focusOutline,
+      outlineOffset: '-2px',
+    },
+
     '& .md-blockquote': {
       borderLeft: `4px solid ${cssVariableTheme.palette.primary.main}`,
       margin: `${cssVariableTheme.spacing.sm} 0`,
@@ -150,6 +155,12 @@ export const MarkdownDisplay = Shade<MarkdownDisplayProps>({
     '& .md-link:hover': {
       textDecoration: 'underline',
     },
+    '& .md-link:focus-visible': {
+      textDecoration: 'underline',
+      outline: cssVariableTheme.action.focusOutline,
+      outlineOffset: '2px',
+      borderRadius: cssVariableTheme.shape.borderRadius.xs,
+    },
 
     '& .md-image': {
       maxWidth: '100%',

package/src/components/markdown/markdown-editor.spec.tsx

@@ -14,7 +14,7 @@ describe('MarkdownEditor', () => {
     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
 
@@ -400,4 +400,127 @@ describe('MarkdownEditor', () => {
       })
     })
   })
+
+  describe('keyboard navigation', () => {
+    it('should have a focusable textarea in side-by-side layout', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <MarkdownEditor value="# Hello" />,
+        })
+
+        await flushUpdates()
+
+        const textarea = document.querySelector('shade-markdown-editor textarea') as HTMLTextAreaElement
+        expect(textarea).not.toBeNull()
+
+        textarea.focus()
+        expect(document.activeElement).toBe(textarea)
+      })
+    })
+
+    it('should have focusable tab buttons in tabs layout', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <MarkdownEditor value="# Hello" layout="tabs" />,
+        })
+
+        await flushUpdates()
+
+        const tabButtons = document.querySelectorAll<HTMLButtonElement>('shade-markdown-editor .shade-tab-btn')
+        expect(tabButtons.length).toBe(2)
+
+        tabButtons[0].focus()
+        expect(document.activeElement).toBe(tabButtons[0])
+
+        tabButtons[1].focus()
+        expect(document.activeElement).toBe(tabButtons[1])
+      })
+    })
+
+    it('should use tabIndex to indicate active tab in controlled tabs layout', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <MarkdownEditor value="# Hello" layout="tabs" />,
+        })
+
+        await flushUpdates()
+
+        const tabButtons = document.querySelectorAll<HTMLButtonElement>('shade-markdown-editor .shade-tab-btn')
+
+        const activeTab = Array.from(tabButtons).find((btn) => btn.classList.contains('active'))
+        const inactiveTab = Array.from(tabButtons).find((btn) => !btn.classList.contains('active'))
+
+        expect(activeTab).not.toBeUndefined()
+        expect(inactiveTab).not.toBeUndefined()
+        expect(activeTab?.tabIndex).toBe(0)
+        expect(inactiveTab?.tabIndex).toBe(-1)
+      })
+    })
+
+    it('should switch tabs when tab button is clicked via keyboard activation', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <MarkdownEditor value="# Hello" layout="tabs" />,
+        })
+
+        await flushUpdates()
+
+        const tabButtons = document.querySelectorAll<HTMLButtonElement>('shade-markdown-editor .shade-tab-btn')
+
+        const previewButton = Array.from(tabButtons).find((btn) => btn.textContent?.includes('Preview'))
+        expect(previewButton).not.toBeUndefined()
+
+        previewButton!.click()
+        await flushUpdates()
+
+        const display = document.querySelector('shade-markdown-editor shade-markdown-display')
+        expect(display).not.toBeNull()
+      })
+    })
+
+    it('should have focusable interactive elements in preview pane', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <MarkdownEditor
+              value={'- [ ] Task A\n- [x] Task B\n\n[A link](https://example.com)'}
+              onValueChange={() => {}}
+            />
+          ),
+        })
+
+        await flushUpdates()
+
+        const checkboxes = document.querySelectorAll(
+          'shade-markdown-editor shade-markdown-display shade-checkbox input[type="checkbox"]',
+        )
+        expect(checkboxes.length).toBe(2)
+
+        const link = document.querySelector('shade-markdown-editor shade-markdown-display .md-link')
+        expect(link).not.toBeNull()
+        ;(checkboxes[0] as HTMLElement).focus()
+        expect(document.activeElement).toBe(checkboxes[0])
+      })
+    })
+  })
 })

package/src/components/markdown/markdown-editor.tsx

@@ -32,7 +32,7 @@ type TabType = 'edit' | 'preview'
  * Supports three layouts: side-by-side, tabs (Edit/Preview), or above-below.
  */
 export const MarkdownEditor = Shade<MarkdownEditorProps>({
-  shadowDomName: 'shade-markdown-editor',
+  customElementName: 'shade-markdown-editor',
   css: {
     display: 'flex',
     fontFamily: cssVariableTheme.typography.fontFamily,

package/src/components/markdown/markdown-input.spec.tsx

@@ -15,7 +15,7 @@ describe('MarkdownInput', () => {
     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/markdown/markdown-input.tsx

@@ -41,7 +41,7 @@ export type MarkdownInputProps = {
  * it is inlined as a `![pasted image](data:...)` Markdown image.
  */
 export const MarkdownInput = Shade<MarkdownInputProps>({
-  shadowDomName: 'shade-markdown-input',
+  customElementName: 'shade-markdown-input',
   css: {
     display: 'block',
     fontFamily: cssVariableTheme.typography.fontFamily,

package/src/components/menu/menu.tsx

@@ -97,7 +97,7 @@ const renderItems = (
 }
 
 export const Menu = Shade<MenuProps>({
-  shadowDomName: 'shade-menu',
+  customElementName: 'shade-menu',
   css: {
     display: 'flex',
     outline: 'none',
@@ -250,7 +250,7 @@ export const Menu = Shade<MenuProps>({
     useHostProps({
       role: mode === 'horizontal' ? 'menubar' : 'menu',
       'data-mode': mode,
-      tabindex: '0',
+      tabIndex: 0,
     })
 
     useHostProps({

package/src/components/modal.spec.tsx

@@ -1,5 +1,5 @@
 import { Injector } from '@furystack/inject'
-import { initializeShadeRoot, createComponent, Shade, flushUpdates } from '@furystack/shades'
+import { initializeShadeRoot, createComponent, Shade, flushUpdates, SpatialNavigationService } from '@furystack/shades'
 import { usingAsync } from '@furystack/utils'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { Modal } from './modal.js'
@@ -58,7 +58,7 @@ describe('Modal', () => {
       let setVisible!: (v: boolean) => void
 
       const Wrapper = Shade({
-        shadowDomName: 'modal-visibility-test-show',
+        customElementName: 'modal-visibility-test-show',
         render: ({ useState }) => {
           const [visible, setter] = useState('visible', false)
           setVisible = setter
@@ -89,7 +89,7 @@ describe('Modal', () => {
       let setVisible!: (v: boolean) => void
 
       const Wrapper = Shade({
-        shadowDomName: 'modal-visibility-test-hide',
+        customElementName: 'modal-visibility-test-hide',
         render: ({ useState }) => {
           const [visible, setter] = useState('visible', true)
           setVisible = setter
@@ -203,7 +203,7 @@ describe('Modal', () => {
       const showAnimation = vi.fn()
 
       const Wrapper = Shade({
-        shadowDomName: 'modal-show-animation-test',
+        customElementName: 'modal-show-animation-test',
         render: ({ useState }) => {
           const [visible, setter] = useState('visible', false)
           setVisible = setter
@@ -308,4 +308,127 @@ describe('Modal', () => {
       })
     })
   })
+
+  describe('spatial navigation', () => {
+    it('should render with data-nav-section attribute when visible', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <Modal isVisible={true}>
+              <div>Content</div>
+            </Modal>
+          ),
+        })
+
+        await flushUpdates()
+        const backdrop = document.querySelector('.shade-backdrop')
+        expect(backdrop?.getAttribute('data-nav-section')).toBeTruthy()
+      })
+    })
+
+    it('should render with custom navSection name', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <Modal isVisible={true} navSection="my-modal">
+              <div>Content</div>
+            </Modal>
+          ),
+        })
+
+        await flushUpdates()
+        const backdrop = document.querySelector('.shade-backdrop')
+        expect(backdrop?.getAttribute('data-nav-section')).toBe('my-modal')
+      })
+    })
+
+    it('should push focus trap when trapFocus is true and service is active', 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: (
+            <Modal isVisible={true} trapFocus={true} navSection="trapped-modal">
+              <div>Content</div>
+            </Modal>
+          ),
+        })
+
+        await flushUpdates()
+
+        expect(pushSpy).toHaveBeenCalledWith('trapped-modal')
+        expect(spatialNav.activeSection.getValue()).toBe('trapped-modal')
+      })
+    })
+
+    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: (
+            <Modal isVisible={true} trapFocus={false}>
+              <div>Content</div>
+            </Modal>
+          ),
+        })
+
+        await flushUpdates()
+
+        expect(pushSpy).not.toHaveBeenCalled()
+        spatialNav.activeSection.setValue('other-section')
+        expect(spatialNav.activeSection.getValue()).toBe('other-section')
+      })
+    })
+
+    it('should pop focus trap when visibility changes from true to false', async () => {
+      let setVisible!: (v: boolean) => void
+
+      const Wrapper = Shade({
+        customElementName: 'modal-trap-visibility-test',
+        render: ({ useState }) => {
+          const [visible, setter] = useState('visible', true)
+          setVisible = setter
+          return (
+            <Modal isVisible={visible} trapFocus={true} navSection="trap-test">
+              <div>Content</div>
+            </Modal>
+          )
+        },
+      })
+
+      await usingAsync(new Injector(), async (injector) => {
+        const spatialNav = injector.getInstance(SpatialNavigationService)
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({ injector, rootElement, jsxElement: <Wrapper /> })
+        await flushUpdates()
+
+        expect(spatialNav.activeSection.getValue()).toBe('trap-test')
+
+        setVisible(false)
+        await flushUpdates()
+
+        expect(spatialNav.activeSection.getValue()).not.toBe('trap-test')
+      })
+    })
+  })
 })

package/src/components/modal.tsx

@@ -1,16 +1,28 @@
-import { Shade, createComponent } from '@furystack/shades'
+import { Shade, createComponent, SpatialNavigationService } from '@furystack/shades'
 import { cssVariableTheme } from '../services/css-variable-theme.js'
 
+let nextModalId = 0
+
 export type ModalProps = {
   backdropStyle?: Partial<CSSStyleDeclaration>
   isVisible: boolean
   onClose?: () => void
   showAnimation?: (el: Element | null) => Promise<unknown>
   hideAnimation?: (el: Element | null) => Promise<unknown>
+  /**
+   * When true, traps spatial navigation within the modal's bounds.
+   * If SpatialNavigationService is not yet instantiated, it will be created with defaults.
+   */
+  trapFocus?: boolean
+  /**
+   * Section name for spatial navigation scoping.
+   * @default 'modal'
+   */
+  navSection?: string
 }
 
 export const Modal = Shade<ModalProps>({
-  shadowDomName: 'shade-modal',
+  customElementName: 'shade-modal',
   css: {
     fontFamily: cssVariableTheme.typography.fontFamily,
     '& .shade-backdrop': {
@@ -22,9 +34,34 @@ export const Modal = Shade<ModalProps>({
       left: '0',
     },
   },
-  render: ({ props, children, useRef }) => {
-    const { isVisible } = props
+  render: ({ props, children, injector, useRef, useDisposable, useState }) => {
+    const { isVisible, trapFocus, navSection } = props
     const backdropRef = useRef<HTMLDivElement>('backdrop')
+    const [generatedSectionId] = useState('generatedSectionId', String(nextModalId++))
+    const sectionName = navSection ?? `modal-${generatedSectionId}`
+
+    useDisposable(
+      'spatial-nav-trap',
+      () => {
+        if (!isVisible || !trapFocus) return { [Symbol.dispose]: () => {} }
+
+        const spatialNav = injector.getInstance(SpatialNavigationService)
+
+        const previousSection = spatialNav.activeSection.getValue()
+        spatialNav.pushFocusTrap(sectionName)
+
+        return {
+          [Symbol.dispose]: () => {
+            try {
+              spatialNav.popFocusTrap(sectionName, previousSection)
+            } catch {
+              // Service may already be disposed during injector teardown
+            }
+          },
+        }
+      },
+      [isVisible, trapFocus],
+    )
 
     if (isVisible) {
       queueMicrotask(() => {
@@ -36,6 +73,7 @@ export const Modal = Shade<ModalProps>({
       <div
         ref={backdropRef}
         className="shade-backdrop"
+        data-nav-section={sectionName}
         onclick={async () => {
           await props.hideAnimation?.(backdropRef.current)
           props.onClose?.()

package/src/components/noty-list.tsx

@@ -23,7 +23,7 @@ export const getDefaultNotyTimeouts = (type: NotyModel['type']) => {
 }
 
 export const NotyComponent = Shade<{ model: NotyModel; onDismiss: () => void }>({
-  shadowDomName: 'shade-noty',
+  customElementName: 'shade-noty',
   css: {
     margin: cssVariableTheme.spacing.xs,
     overflow: 'hidden',
@@ -141,7 +141,7 @@ export const NotyComponent = Shade<{ model: NotyModel; onDismiss: () => void }>(
 })
 
 export const NotyList = Shade({
-  shadowDomName: 'shade-noty-list',
+  customElementName: 'shade-noty-list',
   css: {
     position: 'fixed',
     fontFamily: cssVariableTheme.typography.fontFamily,

package/src/components/page-container/index.tsx

@@ -50,7 +50,7 @@ export type PageContainerProps = {
  * ```
  */
 export const PageContainer = Shade<PageContainerProps>({
-  shadowDomName: 'shade-page-container',
+  customElementName: 'shade-page-container',
   elementBase: HTMLDivElement,
   elementBaseName: 'div',
   css: {

package/src/components/page-container/page-header.tsx

@@ -56,7 +56,7 @@ export type PageHeaderProps = {
  * ```
  */
 export const PageHeader = Shade<PageHeaderProps>({
-  shadowDomName: 'shade-page-header',
+  customElementName: 'shade-page-header',
   css: {
     display: 'block',
     fontFamily: cssVariableTheme.typography.fontFamily,

package/src/components/page-layout/index.spec.tsx

@@ -647,6 +647,26 @@ describe('PageLayout component', () => {
       })
     })
 
+    it('should set data-nav-section="content" on the content area for spatial navigation scoping', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <PageLayout>
+              <div>Content</div>
+            </PageLayout>
+          ),
+        })
+
+        await flushUpdates()
+        const contentArea = document.querySelector('.page-layout-content')
+        expect(contentArea?.getAttribute('data-nav-section')).toBe('content')
+      })
+    })
+
     it('should set CSS variable for zero paddingTop when no AppBar is configured', async () => {
       await usingAsync(new Injector(), async (injector) => {
         const rootElement = document.getElementById('root') as HTMLDivElement