@svgrid/grid 1.2.33 → 2.0.0

package/src/a11y/focus-trap.ts

@@ -0,0 +1,134 @@
+/**
+ * focus-trap - keep Tab / Shift+Tab focus inside a container while it is active,
+ * move focus in on activate, and restore it on release. Shared by SvModal,
+ * SvDrawer, SvMenu and any dialog-like overlay so the WAI-ARIA dialog focus
+ * behaviour lives in ONE place instead of being re-hand-rolled per component.
+ *
+ * Framework-free (DOM only): call `createFocusTrap(el).activate()` from a
+ * component `$effect` and `release()` from its cleanup.
+ *
+ * ```ts
+ * $effect(() => {
+ *   if (!open || !panel) return
+ *   const trap = createFocusTrap(panel)
+ *   trap.activate()
+ *   return () => trap.release()
+ * })
+ * ```
+ */
+
+/** Selector for elements that can, in principle, hold keyboard focus. */
+export const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'area[href]',
+  'button:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  'iframe',
+  'audio[controls]',
+  'video[controls]',
+  '[contenteditable]:not([contenteditable="false"])',
+  '[tabindex]',
+].join(',')
+
+/**
+ * Whether `el` is visible enough to be Tab-focusable. Detects the common,
+ * layout-independent ways of hiding (disabled / hidden attr / aria-hidden /
+ * inline display:none|visibility:hidden) so the check is deterministic in both
+ * real browsers and jsdom. Class-based `display:none` in a real browser is
+ * additionally caught via client rects when layout is available.
+ */
+function isVisible(el: HTMLElement): boolean {
+  if (el.hasAttribute('disabled')) return false
+  if (el.getAttribute('aria-hidden') === 'true') return false
+  if (el.hidden || el.closest('[hidden]')) return false
+  const style = el.style
+  if (style.display === 'none' || style.visibility === 'hidden') return false
+  // Only trust layout when the environment actually lays out (real browsers).
+  if (typeof el.getClientRects === 'function') {
+    const rects = el.getClientRects()
+    // jsdom reports 0 rects for everything, so 0 alone is not "hidden" there;
+    // treat 0 rects as hidden only when SOME element in the doc has layout.
+    if (rects.length === 0 && document.body.getClientRects().length > 0) return false
+  }
+  return true
+}
+
+/** Visible, Tab-focusable descendants of `container`, in DOM order. Elements
+ *  with `tabindex="-1"` are excluded (script-focusable, not Tab-reachable). */
+export function getFocusable(container: HTMLElement): HTMLElement[] {
+  const nodes = Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR))
+  return nodes.filter((el) => {
+    const ti = el.getAttribute('tabindex')
+    if (ti !== null && Number(ti) < 0) return false
+    return isVisible(el)
+  })
+}
+
+export type FocusTrapOptions = {
+  /** Where focus goes on activate: the first focusable (default), the container
+   *  itself, a specific element, or a getter resolved at activate time. */
+  initialFocus?: 'first' | 'container' | HTMLElement | (() => HTMLElement | null)
+  /** Restore focus to the previously-focused element on release. Default true. */
+  returnFocus?: boolean
+  /** Called on Escape while active. Dismissal is usually owned by the layer
+   *  manager, so most consumers leave this unset. */
+  onEscape?: (e: KeyboardEvent) => void
+}
+
+export type FocusTrap = { activate: () => void; release: () => void }
+
+/** Create a focus trap for `container`. Inert until `activate()`. */
+export function createFocusTrap(
+  container: HTMLElement,
+  options: FocusTrapOptions = {},
+): FocusTrap {
+  const { initialFocus = 'first', returnFocus = true } = options
+  let previouslyFocused: HTMLElement | null = null
+  let active = false
+
+  function resolveInitial(): HTMLElement | null {
+    const f = initialFocus
+    if (f === 'container') return container
+    if (f === 'first') return getFocusable(container)[0] ?? container
+    if (typeof f === 'function') return f()
+    return f
+  }
+
+  function onKeydown(e: KeyboardEvent) {
+    if (!active) return
+    if (e.key === 'Escape' && options.onEscape) { options.onEscape(e); return }
+    if (e.key !== 'Tab') return
+    const f = getFocusable(container)
+    if (!f.length) { e.preventDefault(); container.focus(); return }
+    const first = f[0]!
+    const last = f[f.length - 1]!
+    const activeEl = document.activeElement
+    // Focus escaped the container entirely (programmatic blur, etc.): pull back.
+    if (!container.contains(activeEl)) { e.preventDefault(); first.focus(); return }
+    if (e.shiftKey && activeEl === first) { e.preventDefault(); last.focus() }
+    else if (!e.shiftKey && activeEl === last) { e.preventDefault(); first.focus() }
+  }
+
+  function activate() {
+    if (active) return
+    active = true
+    previouslyFocused = document.activeElement as HTMLElement | null
+    // Guarantee the container is a focus fallback even without focusable children.
+    if (!container.hasAttribute('tabindex')) container.setAttribute('tabindex', '-1')
+    document.addEventListener('keydown', onKeydown, true)
+    // Focus on the next microtask so a just-opened panel is in the DOM first.
+    queueMicrotask(() => { if (active) resolveInitial()?.focus() })
+  }
+
+  function release() {
+    if (!active) return
+    active = false
+    document.removeEventListener('keydown', onKeydown, true)
+    if (returnFocus) previouslyFocused?.focus?.()
+    previouslyFocused = null
+  }
+
+  return { activate, release }
+}

package/src/a11y/live-region.test.ts

@@ -0,0 +1,40 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { _resetLiveRegions, announce } from './live-region'
+
+afterEach(() => {
+  _resetLiveRegions()
+})
+
+describe('announce', () => {
+  it('creates a polite status region and sets its text', async () => {
+    announce('3 rows selected')
+    const region = document.querySelector('[aria-live="polite"]')
+    expect(region).not.toBeNull()
+    expect(region!.getAttribute('role')).toBe('status')
+    await Promise.resolve()
+    expect(region!.textContent).toBe('3 rows selected')
+  })
+
+  it('creates a separate assertive alert region', async () => {
+    announce('error!', { assertive: true })
+    const region = document.querySelector('[aria-live="assertive"]')
+    expect(region).not.toBeNull()
+    expect(region!.getAttribute('role')).toBe('alert')
+    await Promise.resolve()
+    expect(region!.textContent).toBe('error!')
+  })
+
+  it('reuses the same region across calls', async () => {
+    announce('first')
+    announce('second')
+    const regions = document.querySelectorAll('[aria-live="polite"]')
+    expect(regions).toHaveLength(1)
+    await Promise.resolve()
+    expect(regions[0]!.textContent).toBe('second')
+  })
+
+  it('ignores empty messages', () => {
+    announce('')
+    expect(document.querySelector('[aria-live]')).toBeNull()
+  })
+})

package/src/a11y/live-region.ts

@@ -0,0 +1,65 @@
+/**
+ * live-region - a single shared pair of visually-hidden ARIA live regions
+ * (polite + assertive) appended to <body> on first use, so any component can
+ * push a transient message to screen readers via `announce()` without each one
+ * shipping its own live region. Used for things like "3 rows selected",
+ * "copied", "no results".
+ */
+let politeEl: HTMLElement | null = null
+let assertiveEl: HTMLElement | null = null
+
+function make(mode: 'polite' | 'assertive'): HTMLElement {
+  const el = document.createElement('div')
+  el.setAttribute('aria-live', mode)
+  el.setAttribute('aria-atomic', 'true')
+  el.setAttribute('role', mode === 'assertive' ? 'alert' : 'status')
+  // Visually hidden, but still exposed to assistive technology.
+  Object.assign(el.style, {
+    position: 'absolute',
+    width: '1px',
+    height: '1px',
+    margin: '-1px',
+    border: '0',
+    padding: '0',
+    overflow: 'hidden',
+    clip: 'rect(0 0 0 0)',
+    clipPath: 'inset(50%)',
+    whiteSpace: 'nowrap',
+  })
+  document.body.appendChild(el)
+  return el
+}
+
+export type AnnounceOptions = {
+  /** Interrupt the user immediately (role="alert"). Default polite. */
+  assertive?: boolean
+}
+
+/** Announce `message` to screen readers. Empty messages are ignored. */
+export function announce(message: string, options: AnnounceOptions = {}): void {
+  if (typeof document === 'undefined' || !message) return
+  const assertive = options.assertive ?? false
+  let el = assertive ? assertiveEl : politeEl
+  // Recreate when missing OR when a prior DOM reset detached the cached node,
+  // so a stale reference can never swallow an announcement silently.
+  if (!el || !el.isConnected) {
+    el = make(assertive ? 'assertive' : 'polite')
+    if (assertive) assertiveEl = el
+    else politeEl = el
+  }
+  // Clear, then set on the next microtask, so an identical consecutive message
+  // still triggers a fresh announcement.
+  el.textContent = ''
+  const target = el
+  queueMicrotask(() => {
+    target.textContent = message
+  })
+}
+
+/** Test helper: tear the shared live regions down. */
+export function _resetLiveRegions(): void {
+  politeEl?.remove()
+  assertiveEl?.remove()
+  politeEl = null
+  assertiveEl = null
+}

package/src/a11y/scroll-lock.test.ts

@@ -0,0 +1,38 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { lockScroll, scrollLockDepth } from './scroll-lock'
+
+afterEach(() => {
+  // Each test balances its own locks; just reset the inline styles.
+  document.body.style.overflow = ''
+  document.body.style.paddingRight = ''
+})
+
+describe('lockScroll', () => {
+  it('hides body overflow while locked and restores it on unlock', () => {
+    document.body.style.overflow = 'auto'
+    const unlock = lockScroll()
+    expect(document.body.style.overflow).toBe('hidden')
+    unlock()
+    expect(document.body.style.overflow).toBe('auto')
+  })
+
+  it('ref-counts nested locks: only the last unlock restores', () => {
+    document.body.style.overflow = 'scroll'
+    const a = lockScroll()
+    const b = lockScroll()
+    expect(scrollLockDepth()).toBe(2)
+    a()
+    expect(document.body.style.overflow).toBe('hidden') // still locked by b
+    b()
+    expect(document.body.style.overflow).toBe('scroll')
+  })
+
+  it('unlock is idempotent', () => {
+    document.body.style.overflow = 'auto'
+    const unlock = lockScroll()
+    unlock()
+    unlock()
+    expect(scrollLockDepth()).toBe(0)
+    expect(document.body.style.overflow).toBe('auto')
+  })
+})

package/src/a11y/scroll-lock.ts

@@ -0,0 +1,41 @@
+/**
+ * scroll-lock - stop the document scrolling behind an overlay, with REF-COUNTING
+ * so nested overlays (a dialog that opens a menu) never fight over
+ * `body.style.overflow`. The first lock records the original values; the last
+ * unlock restores them. Also pads for the vanishing scrollbar so the page
+ * doesn't shift when the lock engages.
+ */
+let locks = 0
+let previousOverflow = ''
+let previousPaddingRight = ''
+
+/** Lock document scroll. Returns an idempotent unlock function. */
+export function lockScroll(): () => void {
+  if (typeof document === 'undefined') return () => {}
+  const body = document.body
+  if (locks === 0) {
+    previousOverflow = body.style.overflow
+    previousPaddingRight = body.style.paddingRight
+    // Compensate for the scrollbar width so fixed/full-width layout stays put.
+    const sbw = window.innerWidth - document.documentElement.clientWidth
+    if (sbw > 0) {
+      const current = parseFloat(getComputedStyle(body).paddingRight) || 0
+      body.style.paddingRight = `${current + sbw}px`
+    }
+    body.style.overflow = 'hidden'
+  }
+  locks++
+  let released = false
+  return () => {
+    if (released) return
+    released = true
+    locks = Math.max(0, locks - 1)
+    if (locks === 0) {
+      body.style.overflow = previousOverflow
+      body.style.paddingRight = previousPaddingRight
+    }
+  }
+}
+
+/** Test helper: current lock depth. */
+export function scrollLockDepth(): number { return locks }

package/src/a11y.contract.test.ts

@@ -1,49 +1,49 @@
-import { describe, expect, it } from 'vitest'
-import {
-  getGridCellA11yProps,
-  getGridHeaderA11yProps,
-  getGridRootA11yProps,
-  getGridRowA11yProps,
-} from './a11y'
-
-function attrsToHtml(attrs: Record<string, string | number | boolean>) {
-  return Object.entries(attrs)
-    .map(([key, value]) => `${key}="${String(value)}"`)
-    .join(' ')
-}
-
-describe('a11y contract rendering', () => {
-  it('builds expected headless markup attributes', () => {
-    const root = getGridRootA11yProps()
-    const header = getGridHeaderA11yProps({
-      sortable: true,
-      sortDirection: 'descending',
-    })
-    const row = getGridRowA11yProps(1)
-    const cell = getGridCellA11yProps({
-      rowIndex: 1,
-      colIndex: 2,
-      selected: true,
-    })
-
-    const html = [
-      `<table ${attrsToHtml(root)}><thead>`,
-      `<tr ${attrsToHtml(row)}>`,
-      `<th ${attrsToHtml(header)}>Age</th>`,
-      `</tr></thead><tbody>`,
-      `<tr ${attrsToHtml(row)}><td ${attrsToHtml(cell)}>42</td></tr>`,
-      `</tbody></table>`,
-    ].join('')
-
-    expect(html).toContain('role="grid"')
-    expect(html).toContain('role="columnheader"')
-    expect(html).toContain('aria-sort="descending"')
-    expect(html).toContain('aria-selected="true"')
-    expect(html).toContain('aria-colindex="2"')
-  })
-
-  it('creates stable active descendant ids', async () => {
-    const { getGridCellDomId } = await import('./a11y')
-    expect(getGridCellDomId('svgrid', 3, 4)).toBe('svgrid_cell_3_4')
-  })
-})
+import { describe, expect, it } from 'vitest'
+import {
+  getGridCellA11yProps,
+  getGridHeaderA11yProps,
+  getGridRootA11yProps,
+  getGridRowA11yProps,
+} from './a11y'
+
+function attrsToHtml(attrs: Record<string, string | number | boolean>) {
+  return Object.entries(attrs)
+    .map(([key, value]) => `${key}="${String(value)}"`)
+    .join(' ')
+}
+
+describe('a11y contract rendering', () => {
+  it('builds expected headless markup attributes', () => {
+    const root = getGridRootA11yProps()
+    const header = getGridHeaderA11yProps({
+      sortable: true,
+      sortDirection: 'descending',
+    })
+    const row = getGridRowA11yProps(1)
+    const cell = getGridCellA11yProps({
+      rowIndex: 1,
+      colIndex: 2,
+      selected: true,
+    })
+
+    const html = [
+      `<table ${attrsToHtml(root)}><thead>`,
+      `<tr ${attrsToHtml(row)}>`,
+      `<th ${attrsToHtml(header)}>Age</th>`,
+      `</tr></thead><tbody>`,
+      `<tr ${attrsToHtml(row)}><td ${attrsToHtml(cell)}>42</td></tr>`,
+      `</tbody></table>`,
+    ].join('')
+
+    expect(html).toContain('role="grid"')
+    expect(html).toContain('role="columnheader"')
+    expect(html).toContain('aria-sort="descending"')
+    expect(html).toContain('aria-selected="true"')
+    expect(html).toContain('aria-colindex="2"')
+  })
+
+  it('creates stable active descendant ids', async () => {
+    const { getGridCellDomId } = await import('./a11y')
+    expect(getGridCellDomId('svgrid', 3, 4)).toBe('svgrid_cell_3_4')
+  })
+})

package/src/a11y.test.ts

@@ -1,59 +1,59 @@
-import { describe, expect, it } from 'vitest'
-import {
-  getGridCellA11yProps,
-  getGridHeaderA11yProps,
-  getGridRootA11yProps,
-  getGridRowA11yProps,
-} from './a11y'
-
-describe('a11y helpers', () => {
-  it('returns grid role props', () => {
-    expect(
-      getGridRootA11yProps({
-        activeDescendantId: 'svgrid_cell_0_0',
-        rowCount: 10,
-        colCount: 5,
-      }),
-    ).toEqual({
-      role: 'grid',
-      tabindex: 0,
-      'aria-activedescendant': 'svgrid_cell_0_0',
-      'aria-rowcount': 10,
-      'aria-colcount': 5,
-    })
-  })
-
-  it('returns header sort semantics', () => {
-    expect(
-      getGridHeaderA11yProps({
-        sortable: true,
-        sortDirection: 'ascending',
-      }),
-    ).toEqual({
-      role: 'columnheader',
-      'aria-sort': 'ascending',
-    })
-  })
-
-  it('returns row and cell indices for accessibility metadata', () => {
-    expect(getGridRowA11yProps(2)).toEqual({
-      role: 'row',
-      'aria-rowindex': 2,
-    })
-
-    expect(
-      getGridCellA11yProps({
-        id: 'svgrid_cell_2_3',
-        rowIndex: 2,
-        colIndex: 3,
-        selected: true,
-      }),
-    ).toEqual({
-      role: 'gridcell',
-      id: 'svgrid_cell_2_3',
-      'aria-colindex': 3,
-      'aria-rowindex': 2,
-      'aria-selected': true,
-    })
-  })
-})
+import { describe, expect, it } from 'vitest'
+import {
+  getGridCellA11yProps,
+  getGridHeaderA11yProps,
+  getGridRootA11yProps,
+  getGridRowA11yProps,
+} from './a11y'
+
+describe('a11y helpers', () => {
+  it('returns grid role props', () => {
+    expect(
+      getGridRootA11yProps({
+        activeDescendantId: 'svgrid_cell_0_0',
+        rowCount: 10,
+        colCount: 5,
+      }),
+    ).toEqual({
+      role: 'grid',
+      tabindex: 0,
+      'aria-activedescendant': 'svgrid_cell_0_0',
+      'aria-rowcount': 10,
+      'aria-colcount': 5,
+    })
+  })
+
+  it('returns header sort semantics', () => {
+    expect(
+      getGridHeaderA11yProps({
+        sortable: true,
+        sortDirection: 'ascending',
+      }),
+    ).toEqual({
+      role: 'columnheader',
+      'aria-sort': 'ascending',
+    })
+  })
+
+  it('returns row and cell indices for accessibility metadata', () => {
+    expect(getGridRowA11yProps(2)).toEqual({
+      role: 'row',
+      'aria-rowindex': 2,
+    })
+
+    expect(
+      getGridCellA11yProps({
+        id: 'svgrid_cell_2_3',
+        rowIndex: 2,
+        colIndex: 3,
+        selected: true,
+      }),
+    ).toEqual({
+      role: 'gridcell',
+      id: 'svgrid_cell_2_3',
+      'aria-colindex': 3,
+      'aria-rowindex': 2,
+      'aria-selected': true,
+    })
+  })
+})

package/src/a11y.ts

@@ -1,59 +1,61 @@
-export type GridSortDirection = 'ascending' | 'descending' | 'none' | 'other'
-
-export type GridColumnA11yInput = {
-  sortable?: boolean
-  sortDirection?: GridSortDirection
-}
-
-export type GridCellA11yInput = {
-  colIndex?: number
-  rowIndex?: number
-  selected?: boolean
-  id?: string
-}
-
-export function getGridRootA11yProps(input: {
-  activeDescendantId?: string | null
-  rowCount?: number
-  colCount?: number
-} = {}) {
-  return {
-    role: 'grid',
-    tabindex: 0,
-    ...(input.activeDescendantId
-      ? { 'aria-activedescendant': input.activeDescendantId }
-      : {}),
-    ...(input.rowCount !== undefined ? { 'aria-rowcount': input.rowCount } : {}),
-    ...(input.colCount !== undefined ? { 'aria-colcount': input.colCount } : {}),
-  } as const
-}
-
-export function getGridHeaderA11yProps(input: GridColumnA11yInput = {}) {
-  const { sortable = false, sortDirection = 'none' } = input
-  return {
-    role: 'columnheader',
-    ...(sortable ? { 'aria-sort': sortDirection } : {}),
-  } as const
-}
-
-export function getGridRowA11yProps(rowIndex?: number) {
-  return {
-    role: 'row',
-    ...(rowIndex !== undefined ? { 'aria-rowindex': rowIndex } : {}),
-  } as const
-}
-
-export function getGridCellA11yProps(input: GridCellA11yInput = {}) {
-  const { colIndex, rowIndex, selected = false, id } = input
-  return {
-    role: 'gridcell',
-    ...(id ? { id } : {}),
-    ...(colIndex !== undefined ? { 'aria-colindex': colIndex } : {}),
-    ...(rowIndex !== undefined ? { 'aria-rowindex': rowIndex } : {}),
-    'aria-selected': selected,
-  } as const
-}
-
-export function getGridCellDomId(baseId: string, rowIndex: number, colIndex: number) {
-  return `${baseId}_cell_${rowIndex}_${colIndex}`
-}
+export type GridSortDirection = 'ascending' | 'descending' | 'none' | 'other'
+
+export type GridColumnA11yInput = {
+  sortable?: boolean
+  sortDirection?: GridSortDirection
+}
+
+export type GridCellA11yInput = {
+  colIndex?: number
+  rowIndex?: number
+  selected?: boolean
+  id?: string
+}
+
+export function getGridRootA11yProps(input: {
+  activeDescendantId?: string | null
+  rowCount?: number
+  colCount?: number
+  /** Use the treegrid role (expandable server group / tree rows are present). */
+  treegrid?: boolean
+} = {}) {
+  return {
+    role: input.treegrid ? 'treegrid' : 'grid',
+    tabindex: 0,
+    ...(input.activeDescendantId
+      ? { 'aria-activedescendant': input.activeDescendantId }
+      : {}),
+    ...(input.rowCount !== undefined ? { 'aria-rowcount': input.rowCount } : {}),
+    ...(input.colCount !== undefined ? { 'aria-colcount': input.colCount } : {}),
+  } as const
+}
+
+export function getGridHeaderA11yProps(input: GridColumnA11yInput = {}) {
+  const { sortable = false, sortDirection = 'none' } = input
+  return {
+    role: 'columnheader',
+    ...(sortable ? { 'aria-sort': sortDirection } : {}),
+  } as const
+}
+
+export function getGridRowA11yProps(rowIndex?: number) {
+  return {
+    role: 'row',
+    ...(rowIndex !== undefined ? { 'aria-rowindex': rowIndex } : {}),
+  } as const
+}
+
+export function getGridCellA11yProps(input: GridCellA11yInput = {}) {
+  const { colIndex, rowIndex, selected = false, id } = input
+  return {
+    role: 'gridcell',
+    ...(id ? { id } : {}),
+    ...(colIndex !== undefined ? { 'aria-colindex': colIndex } : {}),
+    ...(rowIndex !== undefined ? { 'aria-rowindex': rowIndex } : {}),
+    'aria-selected': selected,
+  } as const
+}
+
+export function getGridCellDomId(baseId: string, rowIndex: number, colIndex: number) {
+  return `${baseId}_cell_${rowIndex}_${colIndex}`
+}