@svgrid/grid 2.6.2 → 2.6.4

package/src/a11y/dismissable.test.ts

@@ -1,119 +1,119 @@
-import { afterEach, describe, expect, it } from 'vitest'
-import { createDismissableLayer, dismissableDepth, onScrollOutside } from './dismissable'
-
-function panel(): HTMLElement {
-  const el = document.createElement('div')
-  document.body.appendChild(el)
-  return el
-}
-
-afterEach(() => {
-  document.body.innerHTML = ''
-})
-
-describe('createDismissableLayer', () => {
-  it('dismisses on Escape when topmost', () => {
-    const el = panel()
-    let reason: string | null = null
-    const layer = createDismissableLayer({ element: () => el, onDismiss: (r) => (reason = r) })
-    layer.activate()
-    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
-    expect(reason).toBe('escape')
-    layer.release()
-  })
-
-  it('dismisses on outside pointerdown but not inside', () => {
-    const el = panel()
-    const inside = document.createElement('button')
-    el.appendChild(inside)
-    let reason: string | null = null
-    const layer = createDismissableLayer({ element: () => el, onDismiss: (r) => (reason = r) })
-    layer.activate()
-
-    inside.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true }))
-    expect(reason).toBeNull()
-
-    document.body.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true }))
-    expect(reason).toBe('outside')
-    layer.release()
-  })
-
-  it('treats a pointerdown in ANY of multiple elements as inside', () => {
-    const panelEl = panel()
-    const trigger = panel()
-    let reason: string | null = null
-    const layer = createDismissableLayer({
-      element: () => [panelEl, trigger],
-      onDismiss: (r) => (reason = r),
-    })
-    layer.activate()
-
-    trigger.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true }))
-    expect(reason).toBeNull() // trigger counts as inside
-
-    document.body.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true }))
-    expect(reason).toBe('outside')
-    layer.release()
-  })
-
-  it('only the top layer responds to Escape', () => {
-    const a = panel()
-    const b = panel()
-    const hits: string[] = []
-    const layerA = createDismissableLayer({ element: () => a, onDismiss: () => hits.push('a') })
-    const layerB = createDismissableLayer({ element: () => b, onDismiss: () => hits.push('b') })
-    layerA.activate()
-    layerB.activate()
-    expect(dismissableDepth()).toBe(2)
-
-    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
-    expect(hits).toEqual(['b']) // only the topmost
-
-    layerB.release()
-    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
-    expect(hits).toEqual(['b', 'a']) // now a is on top
-
-    layerA.release()
-    expect(dismissableDepth()).toBe(0)
-  })
-
-  it('close-on-scroll ignores scrolling inside the panel', () => {
-    const el = panel()
-    const list = document.createElement('div') // e.g. the filter menu's facet list
-    el.appendChild(list)
-    let closed = 0
-    const off = onScrollOutside(() => el, () => closed++)
-
-    // Inner scroll containers don't bubble, so this only reaches the capture
-    // listener - it must NOT close the menu the user is scrolling.
-    list.dispatchEvent(new Event('scroll'))
-    el.dispatchEvent(new Event('scroll'))
-    expect(closed).toBe(0)
-
-    // A scroll anywhere else moves the anchor, so the panel closes.
-    document.body.dispatchEvent(new Event('scroll'))
-    expect(closed).toBe(1)
-    document.dispatchEvent(new Event('scroll'))
-    expect(closed).toBe(2)
-
-    off()
-    document.body.dispatchEvent(new Event('scroll'))
-    expect(closed).toBe(2)
-  })
-
-  it('respects closeOnEscape / closeOnOutside flags', () => {
-    const el = panel()
-    let count = 0
-    const layer = createDismissableLayer({
-      element: () => el,
-      onDismiss: () => count++,
-      closeOnEscape: false,
-      closeOnOutside: false,
-    })
-    layer.activate()
-    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
-    document.body.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true }))
-    expect(count).toBe(0)
-    layer.release()
-  })
-})
+import { afterEach, describe, expect, it } from 'vitest'
+import { createDismissableLayer, dismissableDepth, onScrollOutside } from './dismissable'
+
+function panel(): HTMLElement {
+  const el = document.createElement('div')
+  document.body.appendChild(el)
+  return el
+}
+
+afterEach(() => {
+  document.body.innerHTML = ''
+})
+
+describe('createDismissableLayer', () => {
+  it('dismisses on Escape when topmost', () => {
+    const el = panel()
+    let reason: string | null = null
+    const layer = createDismissableLayer({ element: () => el, onDismiss: (r) => (reason = r) })
+    layer.activate()
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+    expect(reason).toBe('escape')
+    layer.release()
+  })
+
+  it('dismisses on outside pointerdown but not inside', () => {
+    const el = panel()
+    const inside = document.createElement('button')
+    el.appendChild(inside)
+    let reason: string | null = null
+    const layer = createDismissableLayer({ element: () => el, onDismiss: (r) => (reason = r) })
+    layer.activate()
+
+    inside.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true }))
+    expect(reason).toBeNull()
+
+    document.body.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true }))
+    expect(reason).toBe('outside')
+    layer.release()
+  })
+
+  it('treats a pointerdown in ANY of multiple elements as inside', () => {
+    const panelEl = panel()
+    const trigger = panel()
+    let reason: string | null = null
+    const layer = createDismissableLayer({
+      element: () => [panelEl, trigger],
+      onDismiss: (r) => (reason = r),
+    })
+    layer.activate()
+
+    trigger.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true }))
+    expect(reason).toBeNull() // trigger counts as inside
+
+    document.body.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true }))
+    expect(reason).toBe('outside')
+    layer.release()
+  })
+
+  it('only the top layer responds to Escape', () => {
+    const a = panel()
+    const b = panel()
+    const hits: string[] = []
+    const layerA = createDismissableLayer({ element: () => a, onDismiss: () => hits.push('a') })
+    const layerB = createDismissableLayer({ element: () => b, onDismiss: () => hits.push('b') })
+    layerA.activate()
+    layerB.activate()
+    expect(dismissableDepth()).toBe(2)
+
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+    expect(hits).toEqual(['b']) // only the topmost
+
+    layerB.release()
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+    expect(hits).toEqual(['b', 'a']) // now a is on top
+
+    layerA.release()
+    expect(dismissableDepth()).toBe(0)
+  })
+
+  it('close-on-scroll ignores scrolling inside the panel', () => {
+    const el = panel()
+    const list = document.createElement('div') // e.g. the filter menu's facet list
+    el.appendChild(list)
+    let closed = 0
+    const off = onScrollOutside(() => el, () => closed++)
+
+    // Inner scroll containers don't bubble, so this only reaches the capture
+    // listener - it must NOT close the menu the user is scrolling.
+    list.dispatchEvent(new Event('scroll'))
+    el.dispatchEvent(new Event('scroll'))
+    expect(closed).toBe(0)
+
+    // A scroll anywhere else moves the anchor, so the panel closes.
+    document.body.dispatchEvent(new Event('scroll'))
+    expect(closed).toBe(1)
+    document.dispatchEvent(new Event('scroll'))
+    expect(closed).toBe(2)
+
+    off()
+    document.body.dispatchEvent(new Event('scroll'))
+    expect(closed).toBe(2)
+  })
+
+  it('respects closeOnEscape / closeOnOutside flags', () => {
+    const el = panel()
+    let count = 0
+    const layer = createDismissableLayer({
+      element: () => el,
+      onDismiss: () => count++,
+      closeOnEscape: false,
+      closeOnOutside: false,
+    })
+    layer.activate()
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+    document.body.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true }))
+    expect(count).toBe(0)
+    layer.release()
+  })
+})

package/src/a11y/dismissable.ts

@@ -1,114 +1,114 @@
-/**
- * dismissable-layer - a global stack of dismissable overlays (dropdowns,
- * popovers, dialogs). Escape and outside-pointer dismiss only the TOP layer, so
- * a menu opened inside a dialog closes the menu first and the dialog second -
- * the ordering users expect from nested overlays. One set of document listeners
- * is shared by every layer instead of each component wiring its own.
- */
-type Reason = 'escape' | 'outside'
-
-/** One element, several elements, or a getter of either. A pointerdown counts
- *  as "inside" when it lands in ANY of them (e.g. a popover's panel AND its
- *  trigger, so clicking the trigger doesn't immediately re-dismiss). */
-export type DismissTarget = HTMLElement | null | ReadonlyArray<HTMLElement | null>
-
-type Layer = {
-  element: () => DismissTarget
-  onDismiss: (reason: Reason) => void
-  closeOnEscape: boolean
-  closeOnOutside: boolean
-}
-
-function containsTarget(target: DismissTarget, node: Node | null): boolean {
-  if (!node) return false
-  const els = Array.isArray(target) ? target : [target as HTMLElement | null]
-  return els.some((el) => el != null && el.contains(node))
-}
-
-const stack: Layer[] = []
-let wired = false
-
-function ensureWired() {
-  if (wired || typeof document === 'undefined') return
-  wired = true
-  document.addEventListener(
-    'keydown',
-    (e) => {
-      if (e.key !== 'Escape') return
-      const top = stack[stack.length - 1]
-      if (top?.closeOnEscape) {
-        e.stopPropagation()
-        top.onDismiss('escape')
-      }
-    },
-    true,
-  )
-  document.addEventListener(
-    'pointerdown',
-    (e) => {
-      const top = stack[stack.length - 1]
-      if (!top?.closeOnOutside) return
-      if (!containsTarget(top.element(), e.target as Node)) top.onDismiss('outside')
-    },
-    true,
-  )
-}
-
-export type DismissableOptions = {
-  /** The panel element(s); a pointerdown outside ALL of them dismisses the layer.
-   *  Pass multiple (e.g. panel + trigger) so clicking the trigger doesn't
-   *  immediately re-dismiss what it just opened. */
-  element: () => DismissTarget
-  onDismiss: (reason: Reason) => void
-  /** Dismiss on Escape when topmost. Default true. */
-  closeOnEscape?: boolean
-  /** Dismiss on outside pointerdown when topmost. Default true. */
-  closeOnOutside?: boolean
-}
-
-export type DismissableLayer = { activate: () => void; release: () => void }
-
-/** Register a dismissable layer. Inert until `activate()`. */
-export function createDismissableLayer(options: DismissableOptions): DismissableLayer {
-  const layer: Layer = {
-    element: options.element,
-    onDismiss: options.onDismiss,
-    closeOnEscape: options.closeOnEscape ?? true,
-    closeOnOutside: options.closeOnOutside ?? true,
-  }
-  return {
-    activate() {
-      ensureWired()
-      if (!stack.includes(layer)) stack.push(layer)
-    },
-    release() {
-      const i = stack.indexOf(layer)
-      if (i >= 0) stack.splice(i, 1)
-    },
-  }
-}
-
-/** Test/introspection helper: current number of active layers. */
-export function dismissableDepth(): number {
-  return stack.length
-}
-
-/**
- * Close-on-scroll for popovers that are position:fixed and anchored by a
- * one-time measurement taken when they open. Scrolling an ancestor slides the
- * anchor out from under them, so they have to close - but scrolling INSIDE
- * them (a long menu, a facet list) must not, which is what a bare capture-phase
- * window listener gets wrong: inner scroll containers don't bubble, so the
- * capture listener sees them and dismisses the panel the user is scrolling.
- *
- * Returns the unsubscribe function.
- */
-export function onScrollOutside(element: () => DismissTarget, onOutside: () => void): () => void {
-  if (typeof window === 'undefined') return () => {}
-  const handler = (event: Event) => {
-    if (containsTarget(element(), event.target as Node)) return
-    onOutside()
-  }
-  window.addEventListener('scroll', handler, true)
-  return () => window.removeEventListener('scroll', handler, true)
-}
+/**
+ * dismissable-layer - a global stack of dismissable overlays (dropdowns,
+ * popovers, dialogs). Escape and outside-pointer dismiss only the TOP layer, so
+ * a menu opened inside a dialog closes the menu first and the dialog second -
+ * the ordering users expect from nested overlays. One set of document listeners
+ * is shared by every layer instead of each component wiring its own.
+ */
+type Reason = 'escape' | 'outside'
+
+/** One element, several elements, or a getter of either. A pointerdown counts
+ *  as "inside" when it lands in ANY of them (e.g. a popover's panel AND its
+ *  trigger, so clicking the trigger doesn't immediately re-dismiss). */
+export type DismissTarget = HTMLElement | null | ReadonlyArray<HTMLElement | null>
+
+type Layer = {
+  element: () => DismissTarget
+  onDismiss: (reason: Reason) => void
+  closeOnEscape: boolean
+  closeOnOutside: boolean
+}
+
+function containsTarget(target: DismissTarget, node: Node | null): boolean {
+  if (!node) return false
+  const els = Array.isArray(target) ? target : [target as HTMLElement | null]
+  return els.some((el) => el != null && el.contains(node))
+}
+
+const stack: Layer[] = []
+let wired = false
+
+function ensureWired() {
+  if (wired || typeof document === 'undefined') return
+  wired = true
+  document.addEventListener(
+    'keydown',
+    (e) => {
+      if (e.key !== 'Escape') return
+      const top = stack[stack.length - 1]
+      if (top?.closeOnEscape) {
+        e.stopPropagation()
+        top.onDismiss('escape')
+      }
+    },
+    true,
+  )
+  document.addEventListener(
+    'pointerdown',
+    (e) => {
+      const top = stack[stack.length - 1]
+      if (!top?.closeOnOutside) return
+      if (!containsTarget(top.element(), e.target as Node)) top.onDismiss('outside')
+    },
+    true,
+  )
+}
+
+export type DismissableOptions = {
+  /** The panel element(s); a pointerdown outside ALL of them dismisses the layer.
+   *  Pass multiple (e.g. panel + trigger) so clicking the trigger doesn't
+   *  immediately re-dismiss what it just opened. */
+  element: () => DismissTarget
+  onDismiss: (reason: Reason) => void
+  /** Dismiss on Escape when topmost. Default true. */
+  closeOnEscape?: boolean
+  /** Dismiss on outside pointerdown when topmost. Default true. */
+  closeOnOutside?: boolean
+}
+
+export type DismissableLayer = { activate: () => void; release: () => void }
+
+/** Register a dismissable layer. Inert until `activate()`. */
+export function createDismissableLayer(options: DismissableOptions): DismissableLayer {
+  const layer: Layer = {
+    element: options.element,
+    onDismiss: options.onDismiss,
+    closeOnEscape: options.closeOnEscape ?? true,
+    closeOnOutside: options.closeOnOutside ?? true,
+  }
+  return {
+    activate() {
+      ensureWired()
+      if (!stack.includes(layer)) stack.push(layer)
+    },
+    release() {
+      const i = stack.indexOf(layer)
+      if (i >= 0) stack.splice(i, 1)
+    },
+  }
+}
+
+/** Test/introspection helper: current number of active layers. */
+export function dismissableDepth(): number {
+  return stack.length
+}
+
+/**
+ * Close-on-scroll for popovers that are position:fixed and anchored by a
+ * one-time measurement taken when they open. Scrolling an ancestor slides the
+ * anchor out from under them, so they have to close - but scrolling INSIDE
+ * them (a long menu, a facet list) must not, which is what a bare capture-phase
+ * window listener gets wrong: inner scroll containers don't bubble, so the
+ * capture listener sees them and dismisses the panel the user is scrolling.
+ *
+ * Returns the unsubscribe function.
+ */
+export function onScrollOutside(element: () => DismissTarget, onOutside: () => void): () => void {
+  if (typeof window === 'undefined') return () => {}
+  const handler = (event: Event) => {
+    if (containsTarget(element(), event.target as Node)) return
+    onOutside()
+  }
+  window.addEventListener('scroll', handler, true)
+  return () => window.removeEventListener('scroll', handler, true)
+}

package/src/a11y/grid-announcements.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest'
+import {
+  formatMessage,
+  filterAnnouncement,
+  selectionAnnouncement,
+} from './grid-announcements'
+import { defaultGridMessages } from '../grid-messages'
+
+const m = defaultGridMessages
+
+describe('formatMessage', () => {
+  it('substitutes placeholders', () => {
+    expect(formatMessage('{a} of {b}', { a: 1, b: 2 })).toBe('1 of 2')
+  })
+
+  it('leaves an unknown placeholder alone rather than blanking it', () => {
+    // A typo in a consumer override should be visible, not silently swallow
+    // the number it was meant to carry.
+    expect(formatMessage('{visible} of {totl}', { visible: 3 })).toBe('3 of {totl}')
+  })
+
+  it('substitutes a placeholder used more than once', () => {
+    expect(formatMessage('{n}/{n}', { n: 7 })).toBe('7/7')
+  })
+})
+
+describe('filterAnnouncement', () => {
+  it('reports the match count while a filter is active', () => {
+    expect(filterAnnouncement(12, 250, true, false, m)).toBe(
+      '12 of 250 rows match the current filters',
+    )
+  })
+
+  it('has a distinct message for zero matches', () => {
+    // "0 of 250 rows match" is technically true but reads as a broken counter.
+    expect(filterAnnouncement(0, 250, true, false, m)).toBe(
+      'No rows match the current filters',
+    )
+  })
+
+  it('confirms that clearing the filters took effect', () => {
+    expect(filterAnnouncement(250, 250, false, true, m)).toBe(
+      'Filters cleared, showing all 250 rows',
+    )
+  })
+
+  it('stays silent when no filter is or was active', () => {
+    // Replacing the data array must not make the grid announce a count nobody
+    // asked for.
+    expect(filterAnnouncement(250, 250, false, false, m)).toBeNull()
+  })
+})
+
+describe('selectionAnnouncement', () => {
+  it('announces select-all', () => {
+    expect(selectionAnnouncement(0, 250, m)).toBe('250 rows selected')
+  })
+
+  it('announces clearing a multi-row selection', () => {
+    expect(selectionAnnouncement(250, 0, m)).toBe('Selection cleared')
+  })
+
+  it('stays silent for a single-row change', () => {
+    // Focus moves to the row and the reader announces it from aria-selected;
+    // a second announcement would talk over that.
+    expect(selectionAnnouncement(0, 1, m)).toBeNull()
+    expect(selectionAnnouncement(3, 4, m)).toBeNull()
+    expect(selectionAnnouncement(1, 0, m)).toBeNull()
+  })
+
+  it('stays silent when the count did not change', () => {
+    expect(selectionAnnouncement(5, 5, m)).toBeNull()
+  })
+
+  it('announces a shrinking range selection', () => {
+    expect(selectionAnnouncement(10, 4, m)).toBe('4 rows selected')
+  })
+})

package/src/a11y/grid-announcements.ts

@@ -0,0 +1,94 @@
+/**
+ * grid-announcements - what the grid says to a screen reader, and when.
+ *
+ * WCAG 4.1.3 covers *status messages*: information the user needs that does not
+ * receive focus. That is a narrow set, and getting the boundary right matters
+ * more than announcing a lot.
+ *
+ * Things the grid deliberately does NOT announce here, because the
+ * accessibility tree already conveys them when focus lands:
+ *
+ *   - the value of the cell you moved to      (roving tabindex moves focus)
+ *   - the sort state of a header              (`aria-sort` on the columnheader)
+ *   - whether the row you are on is selected  (`aria-selected` on the row)
+ *
+ * Announcing those again would make the grid talk over itself. What is left is
+ * genuinely invisible to a screen reader: how many rows survived a filter, and
+ * bulk selection changes that move no focus (select-all, clear).
+ *
+ * These builders are pure so they can be unit-tested without a DOM, and take
+ * their strings from `GridMessages` so an announcement is translated like any
+ * other label.
+ */
+
+/** The subset of `GridMessages` this module reads. */
+export type AnnouncementMessages = {
+  announceFilterResults: string
+  announceNoMatches: string
+  announceFiltersCleared: string
+  announceRowsSelected: string
+  announceSelectionCleared: string
+}
+
+/**
+ * Interpolate `{name}` placeholders.
+ *
+ * The rest of `GridMessages` is single words assembled by the caller (`of`,
+ * `rowsSuffix`). That works for labels but not for sentences: languages order
+ * "12 of 250 match" differently, and a translator handed three separate atoms
+ * cannot fix the order. Announcements are whole sentences, so they get whole
+ * templates. An unknown placeholder is left alone rather than blanked, so a
+ * typo in an override is visible instead of silently eating the number.
+ */
+export function formatMessage(
+  template: string,
+  vars: Record<string, string | number>,
+): string {
+  return template.replace(/\{(\w+)\}/g, (whole, key: string) =>
+    key in vars ? String(vars[key]) : whole,
+  )
+}
+
+/**
+ * What to say after the row set changes, or null to stay quiet.
+ *
+ * `visible` is the count after filtering but BEFORE pagination - the answer to
+ * "how many rows matched", not "how many are on this page".
+ */
+export function filterAnnouncement(
+  visible: number,
+  total: number,
+  filtersActive: boolean,
+  filtersWereActive: boolean,
+  messages: AnnouncementMessages,
+): string | null {
+  if (filtersActive) {
+    if (visible === 0) return messages.announceNoMatches
+    return formatMessage(messages.announceFilterResults, { visible, total })
+  }
+  // Clearing a filter is itself a status change worth confirming; without this
+  // the user hears nothing back and cannot tell the clear took effect.
+  if (filtersWereActive) {
+    return formatMessage(messages.announceFiltersCleared, { total })
+  }
+  return null
+}
+
+/**
+ * What to say after the selection changes, or null to stay quiet.
+ *
+ * Only BULK changes are announced. Selecting one row moves focus to it and the
+ * screen reader reads it as selected from `aria-selected`; announcing "1 row
+ * selected" on top of that is the grid talking over itself. A change of more
+ * than one row cannot have come from a single focus move, so it is the
+ * select-all / range / clear case that otherwise passes silently.
+ */
+export function selectionAnnouncement(
+  previousCount: number,
+  count: number,
+  messages: AnnouncementMessages,
+): string | null {
+  if (Math.abs(count - previousCount) <= 1) return null
+  if (count === 0) return messages.announceSelectionCleared
+  return formatMessage(messages.announceRowsSelected, { count })
+}