@svgrid/grid 2.6.3 → 2.6.5

package/src/SvGrid.svelte

@@ -1900,8 +1900,29 @@
       </label>
     {/if}
 
-    {#if toolPanelEnabled || ctrl.chartingEnabled}
+    {#if toolPanelEnabled || ctrl.chartingEnabled || ctrl.advancedFilter}
       <div class="sv-grid-toolbar">
+        {#if ctrl.advancedFilter}
+          <!--
+            An advanced filter is set from a panel the consumer mounts, which
+            may be scrolled away or in a drawer. Without something here, rows
+            are missing from the grid with nothing on screen to explain why or
+            to undo it. This is that something: state plus a way out.
+          -->
+          <span class="sv-grid-advf-chip">
+            <svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+              <polygon points="22 3 2 3 10 12.46 10 19 14 21 14 12.46 22 3" />
+            </svg>
+            {messages.advancedFilterActive}
+            <button
+              type="button"
+              class="sv-grid-advf-clear"
+              aria-label={messages.advancedFilterClear}
+              title={messages.advancedFilterClear}
+              onclick={() => (ctrl.advancedFilter = null)}
+            >✕</button>
+          </span>
+        {/if}
         {#if toolPanelEnabled}
           <button
             type="button"
@@ -2332,6 +2353,18 @@
                           aria-orientation="vertical"
                           aria-label={`Resize ${toolPanelHeaderLabel(header.column)}`}
                           tabindex="0"
+                          {...(() => {
+                            // A focusable separator is a widget, so ARIA requires
+                            // aria-valuenow. The value it exposes is the column
+                            // width the arrow keys change; 40 is the floor
+                            // enforced in resizeColumnByKeyboard.
+                            const w = Math.round(ctrl.getColumnWidth(header.column.id));
+                            return {
+                              "aria-valuenow": w,
+                              "aria-valuemin": 40,
+                              "aria-valuetext": `${w} pixels`,
+                            };
+                          })()}
                           onpointerdown={(event) =>
                             startColumnResize(event, header.column.id)}
                           onkeydown={(event) =>
@@ -2359,9 +2392,14 @@
                     ></th>
                   {/if}
                   {#if showRowSelectionEffective}
+                    <!-- Filter-row spacer over the selection column. Blank and
+                         non-interactive, so hide it from the a11y tree the same
+                         way the header-row twin does; an exposed empty th is an
+                         axe `empty-table-header` violation. -->
                     <th
                       class="sv-grid-column sv-grid-selection-column"
                       style={`width: ${selectionColumnWidth}px; min-width: ${selectionColumnWidth}px; max-width: ${selectionColumnWidth}px; left: ${showRowNumbersEffective ? rowNumberColumnWidth : 0}px;`}
+                      aria-hidden="true"
                     ></th>
                   {/if}
                   {#if columnVirtualizationEnabled && columnWindowStart > 0}
@@ -2688,6 +2726,7 @@
                           class:sv-grid-cell-cf={hasConditionalFormats}
                           class:sv-grid-cell-invalid={cellValidity.invalid}
                           class:sv-grid-cell-has-note={cellNote != null}
+                          aria-invalid={cellValidity.invalid ? "true" : undefined}
                           title={cellValidity.message ?? undefined}
                           data-svgrid-row={rowIndex}
                           data-svgrid-col={colIndex}
@@ -2935,6 +2974,7 @@
                         class:sv-grid-cell-cf={hasConditionalFormats}
                         class:sv-grid-cell-invalid={cellValidity.invalid}
                         class:sv-grid-cell-has-note={cellNote != null}
+                        aria-invalid={cellValidity.invalid ? "true" : undefined}
                         data-svgrid-row={rowIndex}
                         data-svgrid-col={colIndex}
                         data-col-id={rendered.column.id}
@@ -3008,6 +3048,20 @@
                             cellValue,
                           )}
                         {/if}
+                        {#if cellValidity.invalid && cellValidity.message}
+                          <!-- The validation message, for assistive tech.
+                               On this path the message is shown visually by
+                               the pointerenter tooltip above, which is mouse-
+                               only - a keyboard or screen-reader user would
+                               get `aria-invalid` with no reason attached.
+                               A visually-hidden span inside the cell is read
+                               as part of the cell when focus lands on it, and
+                               unlike `title` it adds no second native tooltip
+                               competing with the custom one. -->
+                          <span class="sv-grid-sr-only"
+                            >{cellValidity.message}</span
+                          >
+                        {/if}
                         {#if cellNote != null && !isEditing}
                           <!-- Excel-style per-cell note indicator. The
                                triangle itself is the hot-zone; hover
@@ -3067,17 +3121,21 @@
                 {#if showRowNumbersEffective}
                   <!-- Row-number column has no aggregate; the digit it normally
                    shows is the row index, which doesn't make sense to sum. -->
-                  <th
+                  <!-- Blank spacer, not a header - see the selection cell below. -->
+                  <td
                     class="sv-grid-column sv-grid-summary-column sv-grid-row-number-column"
                     style={`width: ${rowNumberColumnWidth}px; min-width: ${rowNumberColumnWidth}px; max-width: ${rowNumberColumnWidth}px; left: 0;`}
-                  ></th>
+                  ></td>
                 {/if}
                 {#if showRowSelectionEffective}
-                  <!-- Selection column is checkbox-only; no aggregate. -->
-                  <th
+                  <!-- Selection column is checkbox-only; no aggregate. A blank
+                       spacer in the summary row carries no header semantics, so
+                       it is a td: an empty th is a real a11y violation
+                       (axe `empty-table-header`). -->
+                  <td
                     class="sv-grid-column sv-grid-summary-column sv-grid-selection-column"
                     style={`width: ${selectionColumnWidth}px; min-width: ${selectionColumnWidth}px; max-width: ${selectionColumnWidth}px; left: ${showRowNumbersEffective ? rowNumberColumnWidth : 0}px;`}
-                  ></th>
+                  ></td>
                 {/if}
                 {#if columnVirtualizationEnabled && columnWindowStart > 0}
                   <th

package/src/SvGrid.types.ts

@@ -12,6 +12,7 @@ import type { ConditionalFormat } from "./conditional-formatting";
 import type { GroupDisplayType } from "./group-display";
 import type { GridMessages } from "./grid-messages";
 import type { GridPivotConfig } from "./pivot-view.svelte";
+import type { GridPredicateExpr } from "./filtering/predicate-expr";
 import type { MenuItem } from "./SvMenuList.svelte";
 
 /** The calendar views the scheduler can render. {@link SchedulerConfig}. The
@@ -1060,6 +1061,44 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
     indentPx?: number;
   };
   groupable?: boolean;
+  /**
+   * Group the rows by these column ids, outermost first - `['region',
+   * 'country']` rolls country up inside region.
+   *
+   * ```svelte
+   * <SvGrid {data} {columns} {features} groupBy={['department']} />
+   * ```
+   *
+   * The prop seeds the group-by list and re-applies whenever it changes, so it
+   * works both as initial state and as a controlled value. The column menu and
+   * `api.setGroupBy()` write the same state; a change from either survives
+   * until this prop's own value changes.
+   *
+   * Ignored when `treeData` is set - a row cannot be both a hierarchy node and
+   * bucketed under a group banner.
+   */
+  groupBy?: ReadonlyArray<string>;
+  /**
+   * Which group / tree rows are expanded, keyed by row id.
+   *
+   * Expansion is owned by the engine by default; pass this prop to hoist it
+   * (saved views, "expand everything on load", persisted UI state). Like
+   * `groupBy` it seeds the state and re-applies whenever it changes.
+   *
+   * Group row ids are built from the grouping path, not the display label:
+   * `group_department_Engineering`, and one level deeper
+   * `group_department_Engineering_role_Senior`. Tree rows key off the engine's
+   * row id instead (set `getRowId` to make that your own id). Prefer capturing
+   * the map from `onExpandedChange` over hand-building these keys.
+   */
+  expanded?: Record<string, boolean>;
+  /**
+   * Fired whenever the expanded set changes - chevron clicks,
+   * `api.setRowExpanded()`, `expandAllGroups()` / `collapseAllGroups()`.
+   * Receives the full next map, so it can be written straight back into
+   * `expanded` for a controlled setup.
+   */
+  onExpandedChange?: (expanded: Record<string, boolean>) => void;
   /**
    * Render a subtotal row after each group's children, carrying that group's
    * aggregate values under the columns they belong to (the columns with an
@@ -1369,6 +1408,28 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
    * sorted data on first render. Applied once at mount; user sorting takes over.
    */
   initialSorting?: Array<{ id: string; desc: boolean }>;
+  /**
+   * The advanced-filter expression to start in (Pro). Applied once at mount;
+   * change it afterwards through `api.setAdvancedFilter()`.
+   *
+   * Filtering only happens once `@svgrid/enterprise`'s `enableAdvancedFilter()`
+   * has registered a compiler - without it the expression is stored and
+   * reported but no rows are removed, so the free grid degrades to a no-op
+   * rather than to a wrong row set.
+   */
+  initialAdvancedFilter?: GridPredicateExpr | null;
+  /**
+   * Fires whenever the advanced-filter expression changes, whatever changed it:
+   * `api.setAdvancedFilter()`, `clearAllFilters()`, or the toolbar's clear
+   * control.
+   *
+   * The panel that authors the expression is mounted by you, outside the grid,
+   * so it cannot see a change the grid made on its own. Without this, clearing
+   * from the toolbar leaves that panel showing a filter the grid is no longer
+   * applying. Feed this back into the panel's `expression` prop to keep them
+   * agreeing.
+   */
+  onAdvancedFilterChange?: (expr: GridPredicateExpr | null) => void;
   /**
    * When `true`, the grid still records column-filter / global-filter /
    * facet state (so the menu UI works and indicators light up) but does

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

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