@svgrid/grid 1.2.34 → 2.0.1

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.ts

@@ -16,9 +16,11 @@ 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: 'grid',
+    role: input.treegrid ? 'treegrid' : 'grid',
     tabindex: 0,
     ...(input.activeDescendantId
       ? { 'aria-activedescendant': input.activeDescendantId }

package/src/avatar.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest'
+import { avatarInitials, avatarColorHue } from './avatar'
+
+describe('avatarInitials', () => {
+  it('uses first + last word initials', () => {
+    expect(avatarInitials('Ada Lovelace')).toBe('AL')
+    expect(avatarInitials('a b c')).toBe('AC')
+  })
+
+  it('uses the first two letters of a single word', () => {
+    expect(avatarInitials('Grace')).toBe('GR')
+  })
+
+  it('returns empty for blank input', () => {
+    expect(avatarInitials('   ')).toBe('')
+    expect(avatarInitials('')).toBe('')
+  })
+})
+
+describe('avatarColorHue', () => {
+  it('is deterministic and within 0-359', () => {
+    const a = avatarColorHue('Ada Lovelace')
+    const b = avatarColorHue('Ada Lovelace')
+    expect(a).toBe(b)
+    expect(a).toBeGreaterThanOrEqual(0)
+    expect(a).toBeLessThan(360)
+  })
+
+  it('differs for different names (usually)', () => {
+    expect(avatarColorHue('Alice')).not.toBe(avatarColorHue('Zeno'))
+  })
+})

package/src/avatar.ts

@@ -0,0 +1,21 @@
+/**
+ * avatar - pure helpers behind <SvAvatar>: derive up-to-two-letter initials from
+ * a name, and a stable hue from a string so the same name always gets the same
+ * fallback colour. Framework-free + pure so they are unit-tested directly.
+ */
+
+/** Up to two uppercase initials for `name` (first + last word, or first two
+ *  letters of a single word). Empty string for blank input. */
+export function avatarInitials(name: string): string {
+  const parts = name.trim().split(/\s+/).filter(Boolean)
+  if (!parts.length) return ''
+  if (parts.length === 1) return parts[0]!.slice(0, 2).toUpperCase()
+  return (parts[0]![0]! + parts[parts.length - 1]![0]!).toUpperCase()
+}
+
+/** Deterministic hue (0-359) derived from a string, for the fallback tint. */
+export function avatarColorHue(name: string): number {
+  let h = 0
+  for (let i = 0; i < name.length; i++) h = (h * 31 + name.charCodeAt(i)) % 360
+  return h
+}