@svgrid/grid 2.6.3 → 2.6.5

package/dist/SvGrid.controller.svelte.d.ts

@@ -1,4 +1,4 @@
-import { type CellEditorOption, type Column, type ColumnDef, type Row, type RowData, type TableFeatures, type ChartType, type ChartSpec, type ChartValueFormat } from "./index";
+import { type GridPredicateExpr, type CellEditorOption, type Column, type ColumnDef, type Row, type RowData, type TableFeatures, type ChartType, type ChartSpec, type ChartValueFormat } from "./index";
 import "./sv-grid-scrollbar";
 import { type ColumnStat } from "./conditional-formatting";
 import type { Props, SelectionRange, CellEditState, FilterOperator, MenuPosition, ContextMenuTarget, ChartingConfig } from "./SvGrid.types";
@@ -31,6 +31,7 @@ export declare function createSvGridController<TFeatures extends TableFeatures =
         valueTo2?: string;
         join?: "AND" | "OR";
     }>;
+    advancedFilter: GridPredicateExpr | null;
     verticalScrollbarEl: HTMLElement | null;
     horizontalScrollbarEl: HTMLElement | null;
     scrollVersion: number;

package/dist/SvGrid.controller.svelte.js

@@ -1,4 +1,4 @@
-import { applyGroupAggregate, compileExcelFilter, normalizeForFilter, createColumnVirtualizer, createCoreRowModel, createExpandedRowModel, createFilteredRowModel, createGroupedRowModel, createTreeRowModel, createSvelteVirtualizer, createSortedRowModel, createSvGrid, getGridCellDomId, sortFns, } from "./index";
+import { applyGroupAggregate, applyRowPredicate, compileExcelFilter, getAdvancedFilterEngine, normalizeForFilter, createColumnVirtualizer, createCoreRowModel, createExpandedRowModel, createFilteredRowModel, createGroupedRowModel, createTreeRowModel, createSvelteVirtualizer, createSortedRowModel, createSvGrid, getGridCellDomId, sortFns, } from "./index";
 import { createRowScrollScaling, resolveMaxDomHeight, } from "./virtualization/scroll-scaling";
 import "./sv-grid-scrollbar";
 import { computeColumnStat, formatsNeedingStats, formatNeedsStats, } from "./conditional-formatting";
@@ -21,6 +21,8 @@ import { buildAutoGroupColumns, insertGroupFooters, paginateGroupedRows } from "
 import { createGridApi, } from "./build-api";
 import { createClipboard, } from "./clipboard";
 import { resolveGridMessages } from "./grid-messages";
+import { announce } from "./a11y/live-region";
+import { filterAnnouncement, selectionAnnouncement, } from "./a11y/grid-announcements";
 import { getPivotEngine, hasPivotEngine } from "./pivot-view.svelte";
 import { filterOperatorOptions, fallbackOperatorOption, TEXT_OPERATORS, NUMBER_OPERATORS, DATE_OPERATORS, CHECKBOX_OPERATORS, operatorOption, operatorsForColumn, defaultOperatorFor, operatorLabelFor, } from "./filter-operators";
 import { isBucketableColumn, buildBuckets, isInBucket, } from "./facet-buckets";
@@ -190,6 +192,11 @@ export function createSvGridController(rawProps, domIdBase) {
     let globalFilter = $state("");
     let scrollContainer = $state(null);
     let gridRootEl = $state(null);
+    // Advanced filter (Pro). Seeded once from `initialAdvancedFilter` and driven
+    // thereafter through the API - deliberately NOT a live prop, so it cannot
+    // repeat the `externalFilter` trap of looking controlled while being read
+    // exactly once.
+    let advancedFilter = $state(props.initialAdvancedFilter ?? null);
     let filterRowValues = $state({});
     let filterMenuValues = $state({});
     let verticalScrollbarEl = $state(null);
@@ -508,13 +515,15 @@ export function createSvGridController(rawProps, domIdBase) {
         },
         state: {
             columnFilters: [],
-            grouping: [],
+            // svelte-ignore state_referenced_locally
+            grouping: treeDataConfig ? [] : [...(props.groupBy ?? [])],
             // svelte-ignore state_referenced_locally
             sorting: props.initialSorting ?? [],
             // svelte-ignore state_referenced_locally
             pagination: { pageIndex: 0, pageSize: props.pageSize ?? 10 },
             rowSelection: {},
-            expanded: {},
+            // svelte-ignore state_referenced_locally
+            expanded: { ...(props.expanded ?? {}) },
             activeCell: { rowIndex: 0, colIndex: 0, cellId: null },
         },
     });
@@ -571,6 +580,44 @@ export function createSvGridController(rawProps, domIdBase) {
         lastSeededOrder = incoming;
         userColumnOrder = props.columnOrder ? [...props.columnOrder] : [];
     });
+    // `groupBy` prop -> engine grouping state. Same shape as the `columnOrder`
+    // re-seed above: we only write when the PROP itself changes, so a group-by
+    // set from the column menu or `api.setGroupBy()` is not clobbered on the next
+    // unrelated re-render.
+    let lastSeededGroupBy = (props.groupBy ?? []).join("|");
+    $effect(() => {
+        if (treeDataConfig)
+            return;
+        const incoming = (props.groupBy ?? []).join("|");
+        if (incoming === lastSeededGroupBy)
+            return;
+        lastSeededGroupBy = incoming;
+        grid.setGrouping(() => [...(props.groupBy ?? [])]);
+    });
+    // `expanded` prop -> engine expansion state, and the store -> the
+    // `onExpandedChange` callback. `lastSeededExpanded` is written from BOTH
+    // directions so a controlled parent that echoes the callback value straight
+    // back into the prop does not trigger a redundant re-seed (and so no
+    // prop -> state -> callback -> prop loop can form).
+    let lastSeededExpanded = JSON.stringify(props.expanded ?? {});
+    $effect(() => {
+        const incoming = JSON.stringify(props.expanded ?? {});
+        if (incoming === lastSeededExpanded)
+            return;
+        lastSeededExpanded = incoming;
+        grid.setExpanded(() => ({ ...(props.expanded ?? {}) }));
+    });
+    $effect(() => {
+        let previous = grid.getState().expanded ?? {};
+        return grid.store.subscribe(() => {
+            const next = grid.getState().expanded ?? {};
+            if (next === previous)
+                return;
+            previous = next;
+            lastSeededExpanded = JSON.stringify(next);
+            props.onExpandedChange?.({ ...next });
+        });
+    });
     // Declared here rather than beside the other pagination/state derivations:
     // the auto-group column pipeline below reads it, and a `const` used above its
     // declaration is a type error even though `$derived` is lazy enough at runtime.
@@ -1039,6 +1086,33 @@ export function createSvGridController(rawProps, domIdBase) {
                 return allowed.has(String(raw ?? ""));
             }));
         }
+        // --- Advanced filter (Pro) ---------------------------------------------
+        // Runs LAST for two reasons: it evaluates over the smallest row set, and
+        // its aggregates (`SUM(amount) > 1000`) fold over what the user is
+        // currently looking at rather than the raw dataset. Composed with AND
+        // against the three stages above.
+        //
+        // Fails OPEN throughout. No engine registered (enterprise absent), an
+        // expression the engine cannot compile, or a throw from inside it all
+        // leave `rows` untouched. A half-applied filter that quietly shows the
+        // wrong rows is worse than one that visibly did nothing.
+        if (advancedFilter) {
+            const engine = getAdvancedFilterEngine();
+            if (engine) {
+                try {
+                    const predicate = engine(advancedFilter, {
+                        getValue: getRowColumnValue,
+                        locale: props.filterLocale ?? props.localization?.locale,
+                        rows,
+                    });
+                    if (predicate)
+                        rows = applyRowPredicate(rows, predicate, isGroupRow);
+                }
+                catch {
+                    // Malformed expression: leave the rows alone.
+                }
+            }
+        }
         return rows;
     });
     /**
@@ -1334,6 +1408,72 @@ export function createSvGridController(rawProps, domIdBase) {
     // Resolved chrome messages (English defaults merged with `localeText`). One
     // map every consumer (SvGrid.svelte, GridFooter, menus, filter labels) reads.
     const gridMessages = $derived(resolveGridMessages(props.localization?.text));
+    // ---- Screen-reader status announcements (WCAG 4.1.3) ----
+    // Only genuine status messages belong here: information no focus change
+    // reveals. `a11y/grid-announcements.ts` documents what is deliberately left
+    // unsaid, and why saying it would make the grid talk over itself.
+    /** Data rows before any local filtering - the denominator in "12 of 250". */
+    const unfilteredRowTotal = $derived.by(() => {
+        dataStateVersion;
+        void internalData;
+        return grid.getRowModel().rows.length;
+    });
+    /** Whether any of the five filter surfaces is currently narrowing the rows. */
+    const anyFilterActive = $derived(globalFilter !== "" ||
+        advancedFilter !== null ||
+        Object.keys(filterRowValues).length > 0 ||
+        Object.keys(filterMenuValues).length > 0 ||
+        Object.keys(valueFilters).length > 0);
+    let filtersWereActive = false;
+    let filterAnnounceTimer;
+    $effect(() => {
+        // In external-filter mode the server decides what matched, so the local
+        // counts describe only the page in hand. Announcing them would misreport
+        // the result set, which is worse than staying silent.
+        if (externalFilterEnabled)
+            return;
+        const visible = paginatedRowTotal;
+        const total = unfilteredRowTotal;
+        const active = anyFilterActive;
+        const messages = gridMessages;
+        untrack(() => {
+            const message = filterAnnouncement(visible, total, active, filtersWereActive, messages);
+            filtersWereActive = active;
+            if (!message)
+                return;
+            // Typing in the global filter re-runs this per keystroke. A polite region
+            // queues rather than replaces, so without a debounce the user hears the
+            // count for every prefix they typed before the one they care about.
+            clearTimeout(filterAnnounceTimer);
+            filterAnnounceTimer = setTimeout(() => announce(message), 400);
+        });
+        return () => clearTimeout(filterAnnounceTimer);
+    });
+    // Forward advanced-filter changes to the consumer. Same dedupe-and-skip-first
+    // pattern as the selection forwarder: the panel that authors the expression
+    // lives outside the grid, so a change the grid makes itself (the toolbar's
+    // clear, clearAllFilters) is invisible to it otherwise.
+    let lastAdvancedFilterSerialized = JSON.stringify(untrack(() => advancedFilter) ?? null);
+    $effect(() => {
+        const serialized = JSON.stringify(advancedFilter ?? null);
+        if (serialized === untrack(() => lastAdvancedFilterSerialized))
+            return;
+        untrack(() => {
+            lastAdvancedFilterSerialized = serialized;
+            props.onAdvancedFilterChange?.(advancedFilter ?? null);
+        });
+    });
+    let lastAnnouncedSelectionCount = 0;
+    $effect(() => {
+        const count = Object.values(rowSelectionState).filter(Boolean).length;
+        const messages = gridMessages;
+        untrack(() => {
+            const message = selectionAnnouncement(lastAnnouncedSelectionCount, count, messages);
+            lastAnnouncedSelectionCount = count;
+            if (message)
+                announce(message);
+        });
+    });
     // ---- In-grid pivot mode ----
     // The pivot ENGINE ships in @svgrid/enterprise (registered via the pivot-view
     // seam). When `pivot` is set and the engine is present, the grid runs it over
@@ -2638,6 +2778,8 @@ export function createSvGridController(rawProps, domIdBase) {
         set filterRowValues(v) { filterRowValues = v; },
         get filterMenuValues() { return filterMenuValues; },
         set filterMenuValues(v) { filterMenuValues = v; },
+        get advancedFilter() { return advancedFilter; },
+        set advancedFilter(v) { advancedFilter = v; },
         get verticalScrollbarEl() { return verticalScrollbarEl; },
         set verticalScrollbarEl(v) { verticalScrollbarEl = v; },
         get horizontalScrollbarEl() { return horizontalScrollbarEl; },

package/dist/SvGrid.css

@@ -122,6 +122,38 @@
   border-color: var(--sg-accent, #2563eb);
   color: #fff;
 }
+/* Advanced-filter indicator. Reads as state rather than as another action, so
+   it uses the accent fill the toolbar buttons reserve for `is-active` instead
+   of the neutral button shell. */
+.sv-grid-advf-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 5px 6px 5px 11px;
+  border-radius: 999px;
+  border: 1px solid color-mix(in srgb, var(--sg-accent, #2563eb) 35%, transparent);
+  background: color-mix(in srgb, var(--sg-accent, #2563eb) 12%, transparent);
+  color: var(--sg-accent, #2563eb);
+  font-size: 12.5px;
+  font-weight: 600;
+}
+.sv-grid-advf-clear {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 18px;
+  height: 18px;
+  border: 0;
+  border-radius: 999px;
+  background: transparent;
+  color: inherit;
+  font-size: 11px;
+  cursor: pointer;
+  transition: background-color 120ms ease;
+}
+.sv-grid-advf-clear:hover {
+  background: color-mix(in srgb, var(--sg-accent, #2563eb) 25%, transparent);
+}
 .sv-grid-tool-panel {
   position: absolute;
   top: 0;

package/dist/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/dist/SvGrid.types.d.ts

@@ -4,6 +4,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
  *  `timeline*` views are horizontal: time runs left→right and resources are
@@ -1024,6 +1025,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
@@ -1335,6 +1374,28 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
         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/dist/a11y/grid-announcements.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 declare function formatMessage(template: string, vars: Record<string, string | number>): string;
+/**
+ * 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 declare function filterAnnouncement(visible: number, total: number, filtersActive: boolean, filtersWereActive: boolean, messages: AnnouncementMessages): string | 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 declare function selectionAnnouncement(previousCount: number, count: number, messages: AnnouncementMessages): string | null;

package/dist/a11y/grid-announcements.js

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+/**
+ * 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, vars) {
+    return template.replace(/\{(\w+)\}/g, (whole, key) => 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, total, filtersActive, filtersWereActive, messages) {
+    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, count, messages) {
+    if (Math.abs(count - previousCount) <= 1)
+        return null;
+    if (count === 0)
+        return messages.announceSelectionCleared;
+    return formatMessage(messages.announceRowsSelected, { count });
+}

package/dist/advanced-filter.svelte.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Registration seam for the advanced filter (a `@svgrid/enterprise` feature).
+ *
+ * The grid owns the state and the pipeline slot; enterprise owns the compiler.
+ * Same shape as `pivot-view.svelte.ts`: a module-level `$state` holder with a
+ * register / get / has triple, so the free package carries no commercial code.
+ */
+import type { GridPredicateExpr } from './filtering/predicate-expr';
+/** What the engine needs in order to compile an expression into a predicate. */
+export type AdvancedFilterCompileContext<TRow> = {
+    /**
+     * Resolve a column id to its cell value for a row. The grid passes the same
+     * accessor the column-menu filter stage uses, so a `cmp` on a `fieldFn` or
+     * value-getter column resolves identically in both.
+     */
+    getValue: (row: TRow, columnId: string) => unknown;
+    /** Locale for text folding, matching the column filters. */
+    locale?: string | ReadonlyArray<string>;
+    /**
+     * The rows entering this stage. Aggregates (`SUM(amount) > 1000`) are folded
+     * over exactly these, once, so they see the rows the user is currently
+     * looking at rather than the raw dataset.
+     */
+    rows: ReadonlyArray<TRow>;
+};
+/** A compiled expression: cheap to call once per row. */
+export type CompiledRowPredicate<TRow> = (row: TRow) => boolean;
+/**
+ * Compile an expression to a row predicate.
+ *
+ * Returns `null` when the expression cannot be compiled (an unknown node kind,
+ * an unresolvable column). Must never throw: the grid treats both `null` and a
+ * thrown error as "do not filter", because a half-applied filter silently
+ * showing the wrong rows is worse than an unapplied one.
+ */
+export type AdvancedFilterEngine = <TRow>(expr: GridPredicateExpr, ctx: AdvancedFilterCompileContext<TRow>) => CompiledRowPredicate<TRow> | null;
+/** Register the engine. Enterprise calls this from `enableAdvancedFilter()`. */
+export declare function registerAdvancedFilterEngine(fn: AdvancedFilterEngine | null): void;
+/** The registered engine, or null when enterprise is not installed. */
+export declare function getAdvancedFilterEngine(): AdvancedFilterEngine | null;
+/** Whether an advanced-filter engine has been registered. */
+export declare function hasAdvancedFilterEngine(): boolean;

package/dist/advanced-filter.svelte.js

@@ -0,0 +1,13 @@
+let engine = $state(null);
+/** Register the engine. Enterprise calls this from `enableAdvancedFilter()`. */
+export function registerAdvancedFilterEngine(fn) {
+    engine = fn;
+}
+/** The registered engine, or null when enterprise is not installed. */
+export function getAdvancedFilterEngine() {
+    return engine;
+}
+/** Whether an advanced-filter engine has been registered. */
+export function hasAdvancedFilterEngine() {
+    return engine != null;
+}