@svgrid/grid 2.6.3 → 2.6.4

package/src/a11y.announce.test.ts

@@ -0,0 +1,250 @@
+/**
+ * Verifies the grid actually SPEAKS - that the announcement builders are wired
+ * to a real live region and fire on the state changes they were written for.
+ *
+ * `a11y/grid-announcements.test.ts` proves the message text is right. This file
+ * proves the wiring exists, which is the part that was missing: `announce()`
+ * shipped and was exported for months while `<SvGrid>` never called it, so the
+ * documented "filter and selection announcements" were not happening at all.
+ */
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest'
+import { mount, unmount, flushSync } from 'svelte'
+import SvGrid from './SvGrid.svelte'
+import { _resetLiveRegions } from './a11y/live-region'
+import {
+  tableFeatures,
+  columnFilteringFeature,
+  rowSortingFeature,
+  rowSelectionFeature,
+  createCoreRowModel,
+  createFilteredRowModel,
+  createSortedRowModel,
+} from './index'
+import type { ColumnDef, SvGridApi } from './index'
+
+type Row = { id: string; name: string; team: string }
+
+const features = tableFeatures({
+  columnFilteringFeature,
+  rowSortingFeature,
+  rowSelectionFeature,
+})
+
+const rows: Row[] = [
+  { id: 'r1', name: 'Ada', team: 'Platform' },
+  { id: 'r2', name: 'Grace', team: 'Compilers' },
+  { id: 'r3', name: 'Karen', team: 'Search' },
+  { id: 'r4', name: 'Barbara', team: 'Platform' },
+]
+
+const cols: ColumnDef<typeof features, Row>[] = [
+  { field: 'name', header: 'Name', width: 200 },
+  { field: 'team', header: 'Team', width: 140 },
+]
+
+/** Text currently in the polite live region. */
+const politeText = () =>
+  document.querySelector('[aria-live="polite"]')?.textContent ?? ''
+
+/** `announce()` sets the text on a microtask so a repeat message re-fires. */
+const settle = async () => {
+  await Promise.resolve()
+  await Promise.resolve()
+}
+
+function mountGrid(extraProps: Record<string, unknown> = {}) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  let api: SvGridApi<typeof features, Row> | null = null
+  const app = mount(SvGrid, {
+    target,
+    props: {
+      data: rows,
+      columns: cols,
+      features,
+      _rowModels: {
+        coreRowModel: createCoreRowModel(),
+        filteredRowModel: createFilteredRowModel(),
+        sortedRowModel: createSortedRowModel({} as never),
+      },
+      containerHeight: 300,
+      virtualization: false,
+      columnVirtualization: false,
+      onApiReady: (a: SvGridApi<typeof features, Row>) => {
+        api = a
+      },
+      ...extraProps,
+    } as never,
+  })
+  flushSync()
+  return {
+    target,
+    get api() {
+      return api!
+    },
+    destroy: () => {
+      unmount(app)
+      target.remove()
+    },
+  }
+}
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  _resetLiveRegions()
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+  _resetLiveRegions()
+})
+
+describe('filter announcements', () => {
+  it('says nothing on mount', async () => {
+    const g = mountGrid()
+    try {
+      await vi.advanceTimersByTimeAsync(500)
+      // An unfiltered grid announcing "4 of 4 rows match" would be noise on
+      // every page load.
+      expect(politeText()).toBe('')
+    } finally {
+      g.destroy()
+    }
+  })
+
+  it('reports the match count after a filter narrows the rows', async () => {
+    const g = mountGrid()
+    try {
+      g.api.setState({ globalFilter: 'Platform' })
+      flushSync()
+      await vi.advanceTimersByTimeAsync(500)
+      await settle()
+      expect(politeText()).toBe('2 of 4 rows match the current filters')
+    } finally {
+      g.destroy()
+    }
+  })
+
+  it('reports no matches distinctly', async () => {
+    const g = mountGrid()
+    try {
+      g.api.setState({ globalFilter: 'nothing-matches-this' })
+      flushSync()
+      await vi.advanceTimersByTimeAsync(500)
+      await settle()
+      expect(politeText()).toBe('No rows match the current filters')
+    } finally {
+      g.destroy()
+    }
+  })
+
+  it('debounces so only the final count is announced while typing', async () => {
+    const g = mountGrid()
+    try {
+      // Three keystrokes in quick succession, as a user typing "Pla".
+      for (const s of ['P', 'Pl', 'Pla']) {
+        g.api.setState({ globalFilter: s })
+        flushSync()
+        await vi.advanceTimersByTimeAsync(50)
+      }
+      await vi.advanceTimersByTimeAsync(500)
+      await settle()
+      // A polite region queues rather than replaces, so without the debounce
+      // the user would sit through the count for every prefix.
+      expect(politeText()).toBe('2 of 4 rows match the current filters')
+    } finally {
+      g.destroy()
+    }
+  })
+
+  it('confirms that clearing the filters took effect', async () => {
+    const g = mountGrid()
+    try {
+      g.api.setState({ globalFilter: 'Platform' })
+      flushSync()
+      await vi.advanceTimersByTimeAsync(500)
+      g.api.clearAllFilters()
+      flushSync()
+      await vi.advanceTimersByTimeAsync(500)
+      await settle()
+      expect(politeText()).toBe('Filters cleared, showing all 4 rows')
+    } finally {
+      g.destroy()
+    }
+  })
+
+  it('stays silent in external-filter mode', async () => {
+    // The server decided what matched; the local count describes only the page
+    // in hand, so announcing it would misreport the result set.
+    const g = mountGrid({ externalFilter: true })
+    try {
+      g.api.setState({ globalFilter: 'Platform' })
+      flushSync()
+      await vi.advanceTimersByTimeAsync(500)
+      expect(politeText()).toBe('')
+    } finally {
+      g.destroy()
+    }
+  })
+})
+
+describe('selection announcements', () => {
+  it('announces select-all', async () => {
+    const g = mountGrid()
+    try {
+      g.api.selectAllRows()
+      flushSync()
+      await settle()
+      expect(politeText()).toBe('4 rows selected')
+    } finally {
+      g.destroy()
+    }
+  })
+
+  it('announces clearing a multi-row selection', async () => {
+    const g = mountGrid()
+    try {
+      g.api.selectAllRows()
+      flushSync()
+      await settle()
+      g.api.clearRowSelection()
+      flushSync()
+      await settle()
+      expect(politeText()).toBe('Selection cleared')
+    } finally {
+      g.destroy()
+    }
+  })
+
+  it('stays silent when a single row is selected', async () => {
+    const g = mountGrid()
+    try {
+      g.api.selectRows(['r1'])
+      flushSync()
+      await settle()
+      // Focus lands on the row and the reader announces it from aria-selected.
+      expect(politeText()).toBe('')
+    } finally {
+      g.destroy()
+    }
+  })
+})
+
+describe('announcements are localizable', () => {
+  it('uses a consumer-supplied template, placeholders and all', async () => {
+    const g = mountGrid({
+      localization: {
+        text: { announceFilterResults: '{visible} van de {total} rijen komen overeen' },
+      },
+    })
+    try {
+      g.api.setState({ globalFilter: 'Platform' })
+      flushSync()
+      await vi.advanceTimersByTimeAsync(500)
+      await settle()
+      expect(politeText()).toBe('2 van de 4 rijen komen overeen')
+    } finally {
+      g.destroy()
+    }
+  })
+})

package/src/a11y.axe.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Accessibility tests that run axe-core against a REAL rendered grid.
+ *
+ * The other a11y tests in this package (`a11y.test.ts`, `a11y.contract.test.ts`)
+ * check the ARIA prop builders in isolation, against strings. Useful, but they
+ * cannot catch a violation that only exists once the component is assembled:
+ * a duplicated id, a control with no accessible name, a role nested somewhere
+ * it is not allowed. This file mounts `<SvGrid>` and audits the resulting DOM.
+ *
+ * It runs in the normal vitest suite - which means it runs in CI. The Playwright
+ * e2e suite cannot, because it depends on the private `website/` submodule.
+ *
+ * jsdom limitation, stated rather than hidden: jsdom performs no layout, so
+ * every geometry-dependent rule is meaningless here and is disabled below. The
+ * important one is `color-contrast`, which needs real painting. Contrast is a
+ * property of a theme, not of grid markup, and the guidance for verifying it
+ * against your own theme lives in docs/help/accessibility.md. What this file
+ * does cover is the structural half: roles, names, relationships, and ids.
+ */
+import { describe, expect, it } from 'vitest'
+import { mount, unmount } from 'svelte'
+import axe from 'axe-core'
+import SvGrid from './SvGrid.svelte'
+import {
+  tableFeatures,
+  columnFilteringFeature,
+  rowSortingFeature,
+  rowSelectionFeature,
+  createCoreRowModel,
+  createFilteredRowModel,
+  createSortedRowModel,
+} from './index'
+import type { ColumnDef } from './index'
+
+type Row = { id: string; name: string; team: string; score: number }
+
+const features = tableFeatures({
+  columnFilteringFeature,
+  rowSortingFeature,
+  rowSelectionFeature,
+})
+
+const sortFns = {} as never
+
+const rows: Row[] = [
+  { id: 'r1', name: 'Ada Lovelace', team: 'Platform', score: 91 },
+  { id: 'r2', name: 'Grace Hopper', team: 'Compilers', score: 88 },
+  { id: 'r3', name: 'Karen Sparck Jones', team: 'Search', score: 95 },
+  { id: 'r4', name: 'Barbara Liskov', team: 'Platform', score: 93 },
+]
+
+const cols: ColumnDef<typeof features, Row>[] = [
+  { field: 'name', header: 'Name', width: 200 },
+  { field: 'team', header: 'Team', width: 140 },
+  { field: 'score', header: 'Score', width: 100, align: 'right' },
+]
+
+/**
+ * Rules that depend on layout or painting. jsdom gives every element zero size
+ * and no computed colour, so these produce noise rather than signal.
+ */
+const LAYOUT_DEPENDENT_RULES = [
+  'color-contrast',
+  'scrollable-region-focusable',
+  'target-size',
+]
+
+function mountGrid(extraProps: Record<string, unknown> = {}) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(SvGrid, {
+    target,
+    props: {
+      data: rows,
+      columns: cols,
+      features,
+      _rowModels: {
+        coreRowModel: createCoreRowModel(),
+        filteredRowModel: createFilteredRowModel(),
+        sortedRowModel: createSortedRowModel(sortFns),
+      },
+      containerHeight: 300,
+      virtualization: false,
+      columnVirtualization: false,
+      ...extraProps,
+    } as never,
+  })
+  return {
+    target,
+    destroy: () => {
+      unmount(app)
+      target.remove()
+    },
+  }
+}
+
+async function auditGrid(props: Record<string, unknown> = {}) {
+  const { target, destroy } = mountGrid(props)
+  try {
+    // Let the grid settle (row model + effects) before auditing.
+    await new Promise((r) => setTimeout(r, 0))
+    const results = await axe.run(target, {
+      rules: Object.fromEntries(LAYOUT_DEPENDENT_RULES.map((id) => [id, { enabled: false }])),
+    })
+    return results.violations.map((v) => ({
+      id: v.id,
+      impact: v.impact,
+      help: v.help,
+      nodes: v.nodes.map((n) => n.html).slice(0, 3),
+    }))
+  } finally {
+    destroy()
+  }
+}
+
+describe('axe audit of a rendered grid', () => {
+  it('reports no violations for a plain grid', async () => {
+    expect(await auditGrid()).toEqual([])
+  })
+
+  it('reports no violations with the filter row and global filter shown', async () => {
+    expect(
+      await auditGrid({ showColumnFilters: true, showFilterRow: true, showGlobalFilter: true }),
+    ).toEqual([])
+  })
+
+  it('reports no violations with row selection enabled', async () => {
+    expect(await auditGrid({ showRowSelection: true })).toEqual([])
+  })
+
+  it('reports no violations with pagination shown', async () => {
+    expect(await auditGrid({ showPagination: true, pageSize: 2 })).toEqual([])
+  })
+
+  it('actually audits something - the grid role is present in the tree', async () => {
+    // Guards against the audit silently passing because nothing rendered.
+    const { target, destroy } = mountGrid()
+    try {
+      await new Promise((r) => setTimeout(r, 0))
+      expect(target.querySelector('[role="grid"], table')).not.toBeNull()
+    } finally {
+      destroy()
+    }
+  })
+})
+
+describe('validation is exposed to assistive technology', () => {
+  // `validate` used to mark a bad cell with a red class and a `title` only.
+  // Both are visual: the class carries no semantics at all, and `title` is
+  // unreliably surfaced and unreachable by keyboard. A screen-reader user had
+  // no way to know the cell was rejected, which is WCAG 3.3.1.
+  const validatedCols: ColumnDef<typeof features, Row>[] = [
+    { field: 'name', header: 'Name', width: 200 },
+    {
+      field: 'score',
+      header: 'Score',
+      width: 100,
+      validate: ({ value }) => (Number(value) < 90 ? 'Score must be at least 90' : null),
+    },
+  ]
+
+  it('marks an invalid cell with aria-invalid and keeps the message', async () => {
+    const { target, destroy } = mountGrid({ columns: validatedCols })
+    try {
+      await new Promise((r) => setTimeout(r, 0))
+      const invalid = [...target.querySelectorAll('td[aria-invalid="true"]')]
+      // Grace 88 fails, Ada 91 / Karen 95 / Barbara 93 pass.
+      expect(invalid).toHaveLength(1)
+      // The reason must reach assistive tech, not just the hover tooltip:
+      // either as the accessible description (`title`) or as visually-hidden
+      // text read with the cell. Which one depends on the render path.
+      const reason =
+        invalid[0]?.getAttribute('title') ??
+        invalid[0]?.querySelector('.sv-grid-sr-only')?.textContent
+      expect(reason).toBe('Score must be at least 90')
+    } finally {
+      destroy()
+    }
+  })
+
+  it('leaves valid cells unmarked', async () => {
+    const { target, destroy } = mountGrid({ columns: validatedCols })
+    try {
+      await new Promise((r) => setTimeout(r, 0))
+      expect(target.querySelectorAll('td[aria-invalid]')).toHaveLength(1)
+    } finally {
+      destroy()
+    }
+  })
+
+  it('passes axe with an invalid cell rendered', async () => {
+    expect(await auditGrid({ columns: validatedCols })).toEqual([])
+  })
+})

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,
+    })
+  })
+})