@svgrid/grid 2.6.3 → 2.6.4

package/dist/SvTreeSelect.svelte

@@ -1,235 +1,235 @@
-<script lang="ts" module>
-  export type { TreeSelectNode } from './ui-app.types'
-</script>
-
-<script lang="ts">
-  /**
-   * SvTreeSelect - a single-select dropdown that shows an indented, collapsible
-   * tree in its panel (pick a node from a hierarchy). The open / position /
-   * dismiss / roving / keyboard / ARIA mechanics come from the shared
-   * `createPopoverSelect` core (with ArrowLeft/Right handled via onExtraKey for
-   * expand/collapse); this component adds the tree flattening + rendering. Covers
-   * the "cascader / tree select" pattern without depending on SvTree.
-   */
-  import type { TreeSelectNode } from './ui-app.types'
-  import SvField from './SvField.svelte'
-  import { editorAria, nextEditorId, type SvEditorProps } from './editor-contract'
-  import { portalToBody, popIn } from './popover'
-  import { createPopoverSelect } from './createPopoverSelect.svelte'
-  import { flattenVisible, findNodePath } from './tree-select'
-
-  type Props = Pick<
-    SvEditorProps,
-    'disabled' | 'readonly' | 'label' | 'hint' | 'error' | 'required' | 'invalid' | 'size' | 'id' | 'name' | 'dir' | 'ariaLabel' | 'loading'
-  > & {
-    nodes: ReadonlyArray<TreeSelectNode>
-    value?: string | number | null
-    onChange?: (value: string | number) => void
-    onCommit?: (value: string | number) => void
-    onCancel?: () => void
-    placeholder?: string
-    showPath?: boolean
-    expandedIds?: ReadonlyArray<string | number>
-  }
-
-  let {
-    nodes,
-    value = $bindable<string | number | null>(null),
-    onChange,
-    placeholder = 'Select…',
-    showPath = false,
-    expandedIds = [],
-    disabled = false,
-    readonly = false,
-    label,
-    hint,
-    error,
-    required = false,
-    invalid = false,
-    size = 'md',
-    id,
-    name,
-    dir,
-    ariaLabel,
-    loading = false,
-  }: Props = $props()
-
-  const autoId = nextEditorId('sv-ts')
-  const uid = $derived(id ?? autoId)
-
-  let expanded = $state(new Set<string | number>(expandedIds))
-  let triggerEl = $state<HTMLButtonElement | null>(null)
-  let panelEl = $state<HTMLDivElement | null>(null)
-  let treeEl = $state<HTMLUListElement | null>(null)
-
-  const rows = $derived(flattenVisible(nodes, expanded))
-  const selectedPath = $derived(value == null ? null : findNodePath(nodes, value))
-  const triggerText = $derived(
-    !selectedPath
-      ? ''
-      : showPath
-        ? selectedPath.map((n) => n.label).join(' / ')
-        : selectedPath[selectedPath.length - 1]!.label,
-  )
-
-  function setExpanded(v: string | number, on: boolean) {
-    const next = new Set(expanded)
-    on ? next.add(v) : next.delete(v)
-    expanded = next
-  }
-  function toggleExpand(v: string | number) {
-    setExpanded(v, !expanded.has(v))
-  }
-  function pick(node: TreeSelectNode) {
-    if (node.disabled) return
-    value = node.value // enables bind:value
-    onChange?.(node.value)
-    ts.closePanel()
-  }
-  function onRowClick(row: { node: TreeSelectNode; hasChildren: boolean }) {
-    if (row.hasChildren) toggleExpand(row.node.value)
-    else pick(row.node)
-  }
-
-  const ts = createPopoverSelect({
-    itemCount: () => rows.length,
-    disabled: (i) => !!rows[i]?.node.disabled,
-    readonly: () => readonly,
-    onSelect: (i) => { const row = rows[i]; if (row) onRowClick(row) },
-    getTrigger: () => triggerEl,
-    getPanel: () => panelEl,
-    getInitialFocus: () => treeEl,
-    closeOnSelect: () => false, // onRowClick handles pick + close (branches stay open)
-    initialActive: () => Math.max(0, rows.findIndex((r) => r.node.value === value)),
-    minWidth: () => 220,
-    estimatedHeight: () => 300,
-    onExtraKey: (e, act) => {
-      const row = rows[act]
-      if (!row) return false
-      // "expand" opens the node or steps into the first child; "collapse" closes
-      // it or jumps to the parent - same fallback as createTree's core.
-      const expand = () => {
-        if (row.hasChildren && !row.expanded) setExpanded(row.node.value, true)
-        else if (row.hasChildren && row.expanded) ts.active = Math.min(act + 1, rows.length - 1)
-      }
-      const collapse = () => {
-        if (row.hasChildren && row.expanded) setExpanded(row.node.value, false)
-        else {
-          let pi = act - 1
-          while (pi >= 0 && rows[pi]!.depth >= row.depth) pi--
-          if (pi >= 0) ts.active = pi
-        }
-      }
-      if (e.key === 'ArrowRight') { e.preventDefault(); expand(); return true }
-      if (e.key === 'ArrowLeft') { e.preventDefault(); collapse(); return true }
-      return false
-    },
-    idPrefix: 'sv-ts',
-  })
-</script>
-
-<SvField id={uid} {label} {hint} {error} {required} {dir} {loading}>
-  <div class="sv-ts sv-ts--{size}" class:is-disabled={disabled}>
-    <button
-      bind:this={triggerEl}
-      type="button"
-      class="sv-ts__trigger"
-      class:is-invalid={invalid}
-      {disabled}
-      onclick={() => ts.toggle()}
-      {...ts.triggerProps('tree')}
-      {...editorAria({ id: uid, invalid, required, error, hint, ariaLabel })}
-    >
-      <span class="sv-ts__value" class:is-placeholder={!triggerText}>{triggerText || placeholder}</span>
-      <span class="sv-ts__arrow" aria-hidden="true">▾</span>
-    </button>
-    {#if name}<input type="hidden" {name} value={value ?? ''} />{/if}
-  </div>
-</SvField>
-
-{#if ts.open}
-  <div
-    bind:this={panelEl}
-    class="sv-ts__panel"
-    dir={dir}
-    use:portalToBody
-    use:popIn={{ up: ts.rect.openUpward }}
-    style:position="fixed"
-    style:top={`${ts.rect.top}px`}
-    style:left={`${ts.rect.left}px`}
-    style:min-width={`${ts.rect.width}px`}
-  >
-    <ul
-      bind:this={treeEl}
-      id={ts.panelId}
-      class="sv-ts__tree"
-      role="tree"
-      aria-label={label ?? ariaLabel ?? 'Tree'}
-      aria-activedescendant={ts.activeDescendant()}
-      tabindex="0"
-      style:max-height={`${ts.rect.maxHeight}px`}
-      onkeydown={ts.onPanelKeydown}
-    >
-      {#each rows as row, i (row.node.value)}
-        <li
-          class="sv-ts__row"
-          class:is-active={ts.isActive(i)}
-          class:is-selected={row.node.value === value}
-          class:is-disabled={row.node.disabled}
-          role="treeitem"
-          aria-selected={row.node.value === value}
-          aria-expanded={row.hasChildren ? row.expanded : undefined}
-          style:padding-inline-start={`${8 + row.depth * 16}px`}
-          onclick={() => onRowClick(row)}
-          {...ts.itemProps(i)}
-        >
-          {#if row.hasChildren}
-            <!-- Same chevron as SvTree and the grid's expanders. -->
-            <span class="sv-ts__chev" class:is-open={row.expanded} aria-hidden="true">
-              <svg viewBox="0 0 24 24" width="12" height="12" fill="none" stroke="currentColor"
-                stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="m9 18 6-6-6-6" /></svg>
-            </span>
-          {:else}
-            <span class="sv-ts__chev sv-ts__chev--leaf" aria-hidden="true"></span>
-          {/if}
-          <span class="sv-ts__label">{row.node.label}</span>
-        </li>
-      {/each}
-    </ul>
-  </div>
-{/if}
-
-<style>
-  .sv-ts { --_accent: var(--sg-accent, #2563eb); display: inline-flex; width: 240px; }
-  .sv-ts.is-disabled { opacity: 0.6; }
-  .sv-ts__trigger {
-    flex: 1; min-width: 0; display: flex; align-items: center; gap: 6px; text-align: start;
-    background: var(--sg-input-bg, #fff); color: var(--sg-fg, #0f172a);
-    border: 1px solid var(--sg-input-border, var(--sg-border, #cbd5e1)); border-radius: var(--sg-radius, 8px);
-    font: inherit; cursor: pointer; padding: 0 9px;
-  }
-  .sv-ts--sm .sv-ts__trigger { height: 28px; font-size: 12px; }
-  .sv-ts--md .sv-ts__trigger { height: 34px; font-size: 13px; }
-  .sv-ts--lg .sv-ts__trigger { height: 40px; font-size: 15px; }
-  .sv-ts__trigger:focus-visible { outline: none; border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); }
-  .sv-ts__trigger.is-invalid { border-color: var(--sg-danger, #dc2626); }
-  .sv-ts__value { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-  .sv-ts__value.is-placeholder { color: var(--sg-muted, #94a3b8); }
-  .sv-ts__arrow { color: var(--sg-muted, #64748b); font-size: 10px; }
-
-  :global(.sv-ts__panel) {
-    z-index: 2147483646; max-height: 320px; max-width: 92vw; overflow: hidden;
-    background: var(--sg-bg, #fff); color: var(--sg-fg, #0f172a);
-    border: 1px solid var(--sg-border, #e2e8f0); border-radius: 10px;
-    box-shadow: 0 16px 48px -12px rgba(15, 23, 42, 0.35); font-size: 13px;
-  }
-  :global(.sv-ts__tree) { list-style: none; margin: 0; padding: 4px; overflow: auto; max-height: 320px; outline: none; }
-  :global(.sv-ts__row) { display: flex; align-items: center; gap: 4px; padding: 6px 8px; border-radius: 6px; cursor: pointer; }
-  :global(.sv-ts__row.is-active) { background: var(--sg-row-hover-bg, #f1f5f9); }
-  :global(.sv-ts__row.is-selected) { color: var(--sg-accent, #2563eb); font-weight: 600; }
-  :global(.sv-ts__row.is-disabled) { opacity: 0.5; cursor: not-allowed; }
-  :global(.sv-ts__chev) { width: 14px; flex: none; display: inline-flex; align-items: center; justify-content: center; color: var(--sg-muted, #64748b); transition: transform 0.12s; }
-  :global(.sv-ts__chev.is-open) { transform: rotate(90deg); }
-  :global(.sv-ts__chev--leaf) { visibility: hidden; }
-  :global(.sv-ts__label) { flex: 1; white-space: nowrap; }
-</style>
+<script lang="ts" module>
+  export type { TreeSelectNode } from './ui-app.types'
+</script>
+
+<script lang="ts">
+  /**
+   * SvTreeSelect - a single-select dropdown that shows an indented, collapsible
+   * tree in its panel (pick a node from a hierarchy). The open / position /
+   * dismiss / roving / keyboard / ARIA mechanics come from the shared
+   * `createPopoverSelect` core (with ArrowLeft/Right handled via onExtraKey for
+   * expand/collapse); this component adds the tree flattening + rendering. Covers
+   * the "cascader / tree select" pattern without depending on SvTree.
+   */
+  import type { TreeSelectNode } from './ui-app.types'
+  import SvField from './SvField.svelte'
+  import { editorAria, nextEditorId, type SvEditorProps } from './editor-contract'
+  import { portalToBody, popIn } from './popover'
+  import { createPopoverSelect } from './createPopoverSelect.svelte'
+  import { flattenVisible, findNodePath } from './tree-select'
+
+  type Props = Pick<
+    SvEditorProps,
+    'disabled' | 'readonly' | 'label' | 'hint' | 'error' | 'required' | 'invalid' | 'size' | 'id' | 'name' | 'dir' | 'ariaLabel' | 'loading'
+  > & {
+    nodes: ReadonlyArray<TreeSelectNode>
+    value?: string | number | null
+    onChange?: (value: string | number) => void
+    onCommit?: (value: string | number) => void
+    onCancel?: () => void
+    placeholder?: string
+    showPath?: boolean
+    expandedIds?: ReadonlyArray<string | number>
+  }
+
+  let {
+    nodes,
+    value = $bindable<string | number | null>(null),
+    onChange,
+    placeholder = 'Select…',
+    showPath = false,
+    expandedIds = [],
+    disabled = false,
+    readonly = false,
+    label,
+    hint,
+    error,
+    required = false,
+    invalid = false,
+    size = 'md',
+    id,
+    name,
+    dir,
+    ariaLabel,
+    loading = false,
+  }: Props = $props()
+
+  const autoId = nextEditorId('sv-ts')
+  const uid = $derived(id ?? autoId)
+
+  let expanded = $state(new Set<string | number>(expandedIds))
+  let triggerEl = $state<HTMLButtonElement | null>(null)
+  let panelEl = $state<HTMLDivElement | null>(null)
+  let treeEl = $state<HTMLUListElement | null>(null)
+
+  const rows = $derived(flattenVisible(nodes, expanded))
+  const selectedPath = $derived(value == null ? null : findNodePath(nodes, value))
+  const triggerText = $derived(
+    !selectedPath
+      ? ''
+      : showPath
+        ? selectedPath.map((n) => n.label).join(' / ')
+        : selectedPath[selectedPath.length - 1]!.label,
+  )
+
+  function setExpanded(v: string | number, on: boolean) {
+    const next = new Set(expanded)
+    on ? next.add(v) : next.delete(v)
+    expanded = next
+  }
+  function toggleExpand(v: string | number) {
+    setExpanded(v, !expanded.has(v))
+  }
+  function pick(node: TreeSelectNode) {
+    if (node.disabled) return
+    value = node.value // enables bind:value
+    onChange?.(node.value)
+    ts.closePanel()
+  }
+  function onRowClick(row: { node: TreeSelectNode; hasChildren: boolean }) {
+    if (row.hasChildren) toggleExpand(row.node.value)
+    else pick(row.node)
+  }
+
+  const ts = createPopoverSelect({
+    itemCount: () => rows.length,
+    disabled: (i) => !!rows[i]?.node.disabled,
+    readonly: () => readonly,
+    onSelect: (i) => { const row = rows[i]; if (row) onRowClick(row) },
+    getTrigger: () => triggerEl,
+    getPanel: () => panelEl,
+    getInitialFocus: () => treeEl,
+    closeOnSelect: () => false, // onRowClick handles pick + close (branches stay open)
+    initialActive: () => Math.max(0, rows.findIndex((r) => r.node.value === value)),
+    minWidth: () => 220,
+    estimatedHeight: () => 300,
+    onExtraKey: (e, act) => {
+      const row = rows[act]
+      if (!row) return false
+      // "expand" opens the node or steps into the first child; "collapse" closes
+      // it or jumps to the parent - same fallback as createTree's core.
+      const expand = () => {
+        if (row.hasChildren && !row.expanded) setExpanded(row.node.value, true)
+        else if (row.hasChildren && row.expanded) ts.active = Math.min(act + 1, rows.length - 1)
+      }
+      const collapse = () => {
+        if (row.hasChildren && row.expanded) setExpanded(row.node.value, false)
+        else {
+          let pi = act - 1
+          while (pi >= 0 && rows[pi]!.depth >= row.depth) pi--
+          if (pi >= 0) ts.active = pi
+        }
+      }
+      if (e.key === 'ArrowRight') { e.preventDefault(); expand(); return true }
+      if (e.key === 'ArrowLeft') { e.preventDefault(); collapse(); return true }
+      return false
+    },
+    idPrefix: 'sv-ts',
+  })
+</script>
+
+<SvField id={uid} {label} {hint} {error} {required} {dir} {loading}>
+  <div class="sv-ts sv-ts--{size}" class:is-disabled={disabled}>
+    <button
+      bind:this={triggerEl}
+      type="button"
+      class="sv-ts__trigger"
+      class:is-invalid={invalid}
+      {disabled}
+      onclick={() => ts.toggle()}
+      {...ts.triggerProps('tree')}
+      {...editorAria({ id: uid, invalid, required, error, hint, ariaLabel })}
+    >
+      <span class="sv-ts__value" class:is-placeholder={!triggerText}>{triggerText || placeholder}</span>
+      <span class="sv-ts__arrow" aria-hidden="true">▾</span>
+    </button>
+    {#if name}<input type="hidden" {name} value={value ?? ''} />{/if}
+  </div>
+</SvField>
+
+{#if ts.open}
+  <div
+    bind:this={panelEl}
+    class="sv-ts__panel"
+    dir={dir}
+    use:portalToBody
+    use:popIn={{ up: ts.rect.openUpward }}
+    style:position="fixed"
+    style:top={`${ts.rect.top}px`}
+    style:left={`${ts.rect.left}px`}
+    style:min-width={`${ts.rect.width}px`}
+  >
+    <ul
+      bind:this={treeEl}
+      id={ts.panelId}
+      class="sv-ts__tree"
+      role="tree"
+      aria-label={label ?? ariaLabel ?? 'Tree'}
+      aria-activedescendant={ts.activeDescendant()}
+      tabindex="0"
+      style:max-height={`${ts.rect.maxHeight}px`}
+      onkeydown={ts.onPanelKeydown}
+    >
+      {#each rows as row, i (row.node.value)}
+        <li
+          class="sv-ts__row"
+          class:is-active={ts.isActive(i)}
+          class:is-selected={row.node.value === value}
+          class:is-disabled={row.node.disabled}
+          role="treeitem"
+          aria-selected={row.node.value === value}
+          aria-expanded={row.hasChildren ? row.expanded : undefined}
+          style:padding-inline-start={`${8 + row.depth * 16}px`}
+          onclick={() => onRowClick(row)}
+          {...ts.itemProps(i)}
+        >
+          {#if row.hasChildren}
+            <!-- Same chevron as SvTree and the grid's expanders. -->
+            <span class="sv-ts__chev" class:is-open={row.expanded} aria-hidden="true">
+              <svg viewBox="0 0 24 24" width="12" height="12" fill="none" stroke="currentColor"
+                stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="m9 18 6-6-6-6" /></svg>
+            </span>
+          {:else}
+            <span class="sv-ts__chev sv-ts__chev--leaf" aria-hidden="true"></span>
+          {/if}
+          <span class="sv-ts__label">{row.node.label}</span>
+        </li>
+      {/each}
+    </ul>
+  </div>
+{/if}
+
+<style>
+  .sv-ts { --_accent: var(--sg-accent, #2563eb); display: inline-flex; width: 240px; }
+  .sv-ts.is-disabled { opacity: 0.6; }
+  .sv-ts__trigger {
+    flex: 1; min-width: 0; display: flex; align-items: center; gap: 6px; text-align: start;
+    background: var(--sg-input-bg, #fff); color: var(--sg-fg, #0f172a);
+    border: 1px solid var(--sg-input-border, var(--sg-border, #cbd5e1)); border-radius: var(--sg-radius, 8px);
+    font: inherit; cursor: pointer; padding: 0 9px;
+  }
+  .sv-ts--sm .sv-ts__trigger { height: 28px; font-size: 12px; }
+  .sv-ts--md .sv-ts__trigger { height: 34px; font-size: 13px; }
+  .sv-ts--lg .sv-ts__trigger { height: 40px; font-size: 15px; }
+  .sv-ts__trigger:focus-visible { outline: none; border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); }
+  .sv-ts__trigger.is-invalid { border-color: var(--sg-danger, #dc2626); }
+  .sv-ts__value { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .sv-ts__value.is-placeholder { color: var(--sg-muted, #94a3b8); }
+  .sv-ts__arrow { color: var(--sg-muted, #64748b); font-size: 10px; }
+
+  :global(.sv-ts__panel) {
+    z-index: 2147483646; max-height: 320px; max-width: 92vw; overflow: hidden;
+    background: var(--sg-bg, #fff); color: var(--sg-fg, #0f172a);
+    border: 1px solid var(--sg-border, #e2e8f0); border-radius: 10px;
+    box-shadow: 0 16px 48px -12px rgba(15, 23, 42, 0.35); font-size: 13px;
+  }
+  :global(.sv-ts__tree) { list-style: none; margin: 0; padding: 4px; overflow: auto; max-height: 320px; outline: none; }
+  :global(.sv-ts__row) { display: flex; align-items: center; gap: 4px; padding: 6px 8px; border-radius: 6px; cursor: pointer; }
+  :global(.sv-ts__row.is-active) { background: var(--sg-row-hover-bg, #f1f5f9); }
+  :global(.sv-ts__row.is-selected) { color: var(--sg-accent, #2563eb); font-weight: 600; }
+  :global(.sv-ts__row.is-disabled) { opacity: 0.5; cursor: not-allowed; }
+  :global(.sv-ts__chev) { width: 14px; flex: none; display: inline-flex; align-items: center; justify-content: center; color: var(--sg-muted, #64748b); transition: transform 0.12s; }
+  :global(.sv-ts__chev.is-open) { transform: rotate(90deg); }
+  :global(.sv-ts__chev--leaf) { visibility: hidden; }
+  :global(.sv-ts__label) { flex: 1; white-space: nowrap; }
+</style>

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