@svgrid/grid 1.0.0

package/src/svgrid.set-filter.test.ts

@@ -0,0 +1,270 @@
+/**
+ * Component tests for `api.setFacetFilter()` - the imperative entry
+ * point that powers the three set-filter UX patterns (Excel-style
+ * column-menu, async value loaders, and tree-list cascades). The grid
+ * is filter-source-agnostic; this test exercises the API directly so
+ * coverage is independent of any specific UI implementation.
+ *
+ * Covers:
+ *   - Single column facet filter narrows the displayed rows
+ *   - Multi-value filter (OR within column) accepts every listed value
+ *   - Passing null / empty clears the filter
+ *   - Two columns AND across (different columns)
+ *   - Combines with operator filter from setFilter()
+ *   - Survives unknown values (no crash, just no matches)
+ *   - Unicode / non-ASCII values match exactly (no normalization)
+ */
+
+import { describe, expect, it } from 'vitest'
+import { mount, unmount } from 'svelte'
+import SvGrid from './SvGrid.svelte'
+import {
+  columnFilteringFeature,
+  createCoreRowModel,
+  createFilteredRowModel,
+  createSortedRowModel,
+  rowSortingFeature,
+  sortFns,
+  tableFeatures,
+} from './index'
+import type { ColumnDef, SvGridApi } from './index'
+
+type Order = {
+  id: string
+  region: 'Americas' | 'EMEA' | 'APAC'
+  country: string
+  status: 'open' | 'paid' | 'shipped' | 'delivered' | 'returned'
+  amount: number
+}
+
+const features = tableFeatures({ columnFilteringFeature, rowSortingFeature })
+
+const rows: Order[] = [
+  { id: 'O-1',  region: 'Americas', country: 'United States', status: 'open',      amount:  120 },
+  { id: 'O-2',  region: 'Americas', country: 'United States', status: 'paid',      amount:  240 },
+  { id: 'O-3',  region: 'Americas', country: 'Canada',        status: 'delivered', amount:  410 },
+  { id: 'O-4',  region: 'Americas', country: 'Brazil',        status: 'shipped',   amount:  180 },
+  { id: 'O-5',  region: 'EMEA',     country: 'Germany',       status: 'paid',      amount:  330 },
+  { id: 'O-6',  region: 'EMEA',     country: 'Germany',       status: 'returned',  amount:  205 },
+  { id: 'O-7',  region: 'EMEA',     country: 'France',        status: 'open',      amount:  155 },
+  { id: 'O-8',  region: 'EMEA',     country: 'France',        status: 'shipped',   amount:  420 },
+  { id: 'O-9',  region: 'APAC',     country: 'Japan',         status: 'paid',      amount:  890 },
+  { id: 'O-10', region: 'APAC',     country: 'Japan',         status: 'returned',  amount:  240 },
+  { id: 'O-11', region: 'APAC',     country: 'Australia',     status: 'open',      amount:  175 },
+  { id: 'O-12', region: 'APAC',     country: 'Singapore',     status: 'delivered', amount: 1200 },
+]
+
+const cols: ColumnDef<typeof features, Order>[] = [
+  { field: 'id',      header: 'ID',      width: 90 },
+  { field: 'region',  header: 'Region',  width: 110 },
+  { field: 'country', header: 'Country', width: 160 },
+  { field: 'status',  header: 'Status',  width: 110 },
+  { field: 'amount',  header: 'Amount',  width: 100, align: 'right' },
+]
+
+function mountGrid() {
+  return new Promise<{
+    api: SvGridApi<typeof features, Order>
+    destroy: () => void
+  }>((res, rej) => {
+    const target = document.createElement('div')
+    document.body.appendChild(target)
+    let api: SvGridApi<typeof features, Order> | null = null
+    const app = mount(SvGrid, {
+      target,
+      props: {
+        data: rows,
+        columns: cols,
+        features,
+        _rowModels: {
+          coreRowModel:     createCoreRowModel(),
+          filteredRowModel: createFilteredRowModel(),
+          sortedRowModel:   createSortedRowModel(sortFns),
+        },
+        containerHeight: 360,
+        virtualization: false,
+        columnVirtualization: false,
+        showPagination: false,
+        showColumnFilters: false,
+        showGlobalFilter: false,
+        showRowSelection: false,
+        onApiReady(received: SvGridApi<typeof features, Order>) {
+          api = received
+          res({ api, destroy: () => { unmount(app); target.remove() } })
+        },
+      } as any,
+    })
+    queueMicrotask(() => { if (!api) rej(new Error('onApiReady never fired')) })
+  })
+}
+
+const tick = () => new Promise<void>((r) => queueMicrotask(r))
+
+describe('SvGridApi.setFacetFilter - single column', () => {
+  it('narrows to one allowed value', async () => {
+    const { api, destroy } = await mountGrid()
+    try {
+      api.setFacetFilter('region', ['EMEA'])
+      await tick()
+      const ids = api.getDisplayedRows().map((r) => r.id)
+      expect(ids).toEqual(['O-5', 'O-6', 'O-7', 'O-8'])
+    } finally { destroy() }
+  })
+
+  it('accepts multiple values (OR within column)', async () => {
+    const { api, destroy } = await mountGrid()
+    try {
+      api.setFacetFilter('region', ['EMEA', 'APAC'])
+      await tick()
+      const regions = new Set(api.getDisplayedRows().map((r) => r.region))
+      expect(regions).toEqual(new Set(['EMEA', 'APAC']))
+      expect(api.getDisplayedRows().length).toBe(8)
+    } finally { destroy() }
+  })
+
+  it('empty allowed array filters everything out', async () => {
+    // An empty SET is treated as a clear (matches the implementation -
+    // see `setFacetFilter`'s null branch). Verify the documented
+    // behavior: empty array clears.
+    const { api, destroy } = await mountGrid()
+    try {
+      api.setFacetFilter('region', [])
+      await tick()
+      expect(api.getDisplayedRows().length).toBe(rows.length)
+    } finally { destroy() }
+  })
+
+  it('null clears the filter', async () => {
+    const { api, destroy } = await mountGrid()
+    try {
+      api.setFacetFilter('region', ['EMEA'])
+      await tick()
+      expect(api.getDisplayedRows().length).toBe(4)
+      api.setFacetFilter('region', null)
+      await tick()
+      expect(api.getDisplayedRows().length).toBe(rows.length)
+    } finally { destroy() }
+  })
+})
+
+describe('SvGridApi.setFacetFilter - multi-column AND', () => {
+  it('region + status both narrow', async () => {
+    const { api, destroy } = await mountGrid()
+    try {
+      api.setFacetFilter('region', ['EMEA'])
+      api.setFacetFilter('status', ['paid', 'returned'])
+      await tick()
+      const ids = api.getDisplayedRows().map((r) => r.id)
+      expect(ids).toEqual(['O-5', 'O-6']) // EMEA rows whose status is paid or returned
+    } finally { destroy() }
+  })
+
+  it('region + country + status all compose', async () => {
+    const { api, destroy } = await mountGrid()
+    try {
+      api.setFacetFilter('region',  ['APAC'])
+      api.setFacetFilter('country', ['Japan', 'Singapore'])
+      api.setFacetFilter('status',  ['delivered'])
+      await tick()
+      const ids = api.getDisplayedRows().map((r) => r.id)
+      expect(ids).toEqual(['O-12']) // APAC + Singapore + delivered
+    } finally { destroy() }
+  })
+})
+
+describe('SvGridApi.setFacetFilter - composition with operator filters', () => {
+  it('facet narrows; setFilter further narrows on the same column id', async () => {
+    const { api, destroy } = await mountGrid()
+    try {
+      api.setFacetFilter('region', ['Americas', 'EMEA'])
+      api.setFilter('country', { operator: 'startsWith', value: 'g' }) // → Germany
+      await tick()
+      const ids = api.getDisplayedRows().map((r) => r.id)
+      expect(ids).toEqual(['O-5', 'O-6'])
+    } finally { destroy() }
+  })
+
+  it('clearing the facet but keeping setFilter only honors setFilter', async () => {
+    const { api, destroy } = await mountGrid()
+    try {
+      api.setFacetFilter('region', ['EMEA'])
+      api.setFilter('country', { operator: 'contains', value: 'fran' })
+      await tick()
+      expect(api.getDisplayedRows().map((r) => r.id)).toEqual(['O-7', 'O-8'])
+
+      api.setFacetFilter('region', null)
+      await tick()
+      expect(api.getDisplayedRows().map((r) => r.id)).toEqual(['O-7', 'O-8'])
+    } finally { destroy() }
+  })
+})
+
+describe('SvGridApi.setFacetFilter - edge cases', () => {
+  it('unknown allowed values silently match nothing', async () => {
+    const { api, destroy } = await mountGrid()
+    try {
+      api.setFacetFilter('status', ['SHIPPED_IN_TRANSIT', 'PENDING_REVIEW'])
+      await tick()
+      expect(api.getDisplayedRows().length).toBe(0)
+    } finally { destroy() }
+  })
+
+  it('mixed known + unknown values: known values still match', async () => {
+    const { api, destroy } = await mountGrid()
+    try {
+      api.setFacetFilter('status', ['shipped', 'UNKNOWN_VALUE'])
+      await tick()
+      const ids = api.getDisplayedRows().map((r) => r.id)
+      expect(ids).toEqual(['O-4', 'O-8'])
+    } finally { destroy() }
+  })
+})
+
+describe('SvGridApi.setFacetFilter - simulates the tree-list pattern', () => {
+  // Demo 111's tree picker resolves a hierarchical selection to a flat
+  // list of leaf values, then calls setFacetFilter. These tests
+  // exercise that contract.
+
+  it('simulates a tree drop: select Americas → all American countries', async () => {
+    const { api, destroy } = await mountGrid()
+    try {
+      // Leaf descendants of the "Americas" tree node:
+      const americansCountries = ['United States', 'Canada', 'Brazil']
+      api.setFacetFilter('country', americansCountries)
+      await tick()
+      const regions = new Set(api.getDisplayedRows().map((r) => r.region))
+      expect(regions).toEqual(new Set(['Americas']))
+    } finally { destroy() }
+  })
+
+  it('simulates a partial-tree selection: only Japan + Singapore', async () => {
+    const { api, destroy } = await mountGrid()
+    try {
+      api.setFacetFilter('country', ['Japan', 'Singapore'])
+      await tick()
+      const ids = api.getDisplayedRows().map((r) => r.id)
+      expect(ids).toEqual(['O-9', 'O-10', 'O-12'])
+    } finally { destroy() }
+  })
+})
+
+describe('SvGridApi.setFacetFilter - simulates the async loader pattern', () => {
+  // Demo 111's async card emulates a server returning the distinct
+  // emails. The grid is told the final selection via setFacetFilter -
+  // there's no special "loading" code path inside the grid, the
+  // consumer's UI handles that. Verify the contract works regardless of
+  // whether the values were enumerated client-side or server-side.
+
+  it('async-loaded values: select user-resolved subset', async () => {
+    const { api, destroy } = await mountGrid()
+    try {
+      // Pretend the user clicked these from a server-loaded value list.
+      const userSelected = ['Germany', 'France']
+      api.setFacetFilter('country', userSelected)
+      await tick()
+      const regions = new Set(api.getDisplayedRows().map((r) => r.region))
+      expect(regions).toEqual(new Set(['EMEA']))
+      expect(api.getDisplayedRows().length).toBe(4)
+    } finally { destroy() }
+  })
+})

package/src/svgrid.wrapper.test.ts

@@ -0,0 +1,35 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import SvGrid from './SvGrid.svelte'
+
+describe('SvGrid wrapper', () => {
+  it('exports a production wrapper component', () => {
+    expect(SvGrid).toBeDefined()
+  })
+
+  it('contains full-wrapper controls and aria-activedescendant wiring', () => {
+    const source = readFileSync(resolve(__dirname, './SvGrid.svelte'), 'utf-8')
+    expect(source).toContain('Filter all rows')
+    expect(source).toContain('Previous')
+    expect(source).toContain('role="status"')
+    expect(source).toContain('role="alert"')
+    expect(source).toContain('activeDescendantId')
+    expect(source).toContain('getGridRootA11yProps')
+    expect(source).toContain('data-svgrid-header-col')
+    expect(source).toContain('data-svgrid-row')
+    expect(source).toContain('createSvelteVirtualizer')
+    expect(source).toContain('props.virtualization ?? true')
+    expect(source).toContain('virtualizer.getVirtualItems()')
+    expect(source).toContain('createColumnVirtualizer')
+    expect(source).toContain('data-selected-range')
+    expect(source).toContain('enableInlineEditing')
+    expect(source).toContain('showFilterMenu')
+    expect(source).toContain('<tfoot')
+    expect(source).toContain('editorType === "number"')
+    expect(source).toContain('editorType === "date"')
+    expect(source).toContain('editorType === "checkbox"')
+    expect(source).toContain('applyExcelFilter')
+    expect(source).toContain('showFilterRow')
+  })
+})

package/src/test-setup.ts

@@ -0,0 +1,37 @@
+// Vitest setup. jsdom doesn't ship ResizeObserver, IntersectionObserver,
+// or the layout APIs SvGrid touches inside its mount effects. Provide
+// minimal no-op stubs so component mounting completes without crashing.
+
+if (typeof globalThis.ResizeObserver === 'undefined') {
+  // @ts-expect-error - assigning to a globalThis property the env doesn't ship
+  globalThis.ResizeObserver = class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  }
+}
+
+if (typeof globalThis.IntersectionObserver === 'undefined') {
+  // @ts-expect-error - same
+  globalThis.IntersectionObserver = class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords() {
+      return []
+    }
+  }
+}
+
+// jsdom's HTMLElement.scrollIntoView is a no-op; some grid code calls it
+// during the first effect. Make sure the method exists on every element.
+if (typeof Element !== 'undefined' && !Element.prototype.scrollIntoView) {
+  // @ts-expect-error - patching a missing DOM method
+  Element.prototype.scrollIntoView = function () {}
+}
+
+// jsdom returns 0 for offset* and getBoundingClientRect; the grid only uses
+// these for visual layout (column widths, virtualization windowing), so the
+// zeros are harmless for behavioral tests.
+
+export {}

package/src/transaction.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest'
+import { mount, unmount } from 'svelte'
+import SvGrid from './SvGrid.svelte'
+import {
+  createCoreRowModel,
+  createFilteredRowModel,
+  createSortedRowModel,
+  sortFns,
+  tableFeatures,
+} from './index'
+import type { ColumnDef, SvGridApi } from './index'
+
+type Order = { id: string; symbol: string; price: number }
+
+const features = tableFeatures({})
+const seed: Order[] = [
+  { id: 'a', symbol: 'AAPL', price: 100 },
+  { id: 'b', symbol: 'MSFT', price: 200 },
+  { id: 'c', symbol: 'NVDA', price: 300 },
+]
+const columns: ColumnDef<typeof features, Order>[] = [
+  { field: 'symbol', header: 'Symbol' },
+  { field: 'price', header: 'Price' },
+]
+
+function mountGrid(): Promise<{ api: SvGridApi<typeof features, Order>; destroy: () => void }> {
+  return new Promise((resolve, reject) => {
+    const target = document.createElement('div')
+    document.body.appendChild(target)
+    let captured: SvGridApi<typeof features, Order> | null = null
+    const app = mount(SvGrid, {
+      target,
+      props: {
+        data: seed,
+        columns,
+        features,
+        getRowId: (o: Order) => o.id,
+        _rowModels: {
+          coreRowModel: createCoreRowModel(),
+          filteredRowModel: createFilteredRowModel(),
+          sortedRowModel: createSortedRowModel(sortFns),
+        },
+        containerHeight: 400,
+        virtualization: false,
+        onApiReady(api: SvGridApi<typeof features, Order>) {
+          captured = api
+          resolve({ api, destroy: () => { unmount(app); target.remove() } })
+        },
+      } as any,
+    })
+    queueMicrotask(() => { if (!captured) reject(new Error('onApiReady never fired')) })
+  })
+}
+
+const tick = () => Promise.resolve()
+
+describe('api.applyTransaction', () => {
+  it('adds, updates (by id), and removes (by id) in one batch', async () => {
+    const { api, destroy } = await mountGrid()
+    try {
+      const result = api.applyTransaction({
+        add: [{ id: 'd', symbol: 'AMZN', price: 400 }],
+        update: [{ id: 'b', symbol: 'MSFT', price: 222 }],
+        remove: ['a'],
+      })
+      await tick()
+      expect(result).toEqual({ added: 1, updated: 1, removed: 1 })
+      const data = api.getData()
+      expect(data.map((o) => o.id)).toEqual(['b', 'c', 'd'])
+      expect(data.find((o) => o.id === 'b')?.price).toBe(222)
+    } finally {
+      destroy()
+    }
+  })
+
+  it('removes by row reference too', async () => {
+    const { api, destroy } = await mountGrid()
+    try {
+      const ref = api.getData()[2]! // 'c'
+      const result = api.applyTransaction({ remove: [ref] })
+      await tick()
+      expect(result.removed).toBe(1)
+      expect(api.getData().map((o) => o.id)).toEqual(['a', 'b'])
+    } finally {
+      destroy()
+    }
+  })
+
+  it('ignores unknown ids without throwing', async () => {
+    const { api, destroy } = await mountGrid()
+    try {
+      const result = api.applyTransaction({ update: [{ id: 'zzz', symbol: 'X', price: 1 }], remove: ['nope'] })
+      await tick()
+      expect(result).toEqual({ added: 0, updated: 0, removed: 0 })
+      expect(api.getData()).toHaveLength(3)
+    } finally {
+      destroy()
+    }
+  })
+})

package/src/virtualization/column-virtualizer.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+import { createColumnVirtualizer } from './column-virtualizer'
+
+describe('column virtualizer', () => {
+  it('computes horizontal window', () => {
+    const v = createColumnVirtualizer({
+      count: 1000,
+      viewportWidth: 700,
+      overscan: 3,
+      estimateSize: () => 140,
+    })
+    const items = v.getVirtualItems()
+    expect(items[0]?.index).toBe(0)
+    expect(items.length).toBeGreaterThan(0)
+  })
+
+  it('updates indices on horizontal scroll', () => {
+    const v = createColumnVirtualizer({
+      count: 1000,
+      viewportWidth: 700,
+      estimateSize: () => 140,
+    })
+    v.setHorizontalOffset(2800)
+    const state = v.getState()
+    expect(state.startIndex).toBeGreaterThan(0)
+  })
+})

package/src/virtualization/column-virtualizer.ts

@@ -0,0 +1,30 @@
+import { createVirtualizer } from './virtualizer'
+
+export type ColumnSizeEstimator = (index: number) => number
+
+export function createColumnVirtualizer(input: {
+  count: number
+  viewportWidth: number
+  scrollOffset?: number
+  overscan?: number
+  /** Either a uniform size (number) or a per-column size function. */
+  estimateSize?: number | ColumnSizeEstimator
+}) {
+  const virtualizer = createVirtualizer({
+    count: input.count,
+    estimateSize: input.estimateSize ?? 140,
+    viewportHeight: input.viewportWidth,
+    scrollOffset: input.scrollOffset ?? 0,
+    overscan: input.overscan ?? 4,
+  })
+
+  return {
+    ...virtualizer,
+    setViewportWidth(viewportWidth: number) {
+      virtualizer.setViewportHeight(viewportWidth)
+    },
+    setHorizontalOffset(scrollOffset: number) {
+      virtualizer.setScrollOffset(scrollOffset)
+    },
+  }
+}

package/src/virtualization/svelte-virtualizer.svelte.ts

@@ -0,0 +1,24 @@
+import { createVirtualizer } from './virtualizer'
+import type { VirtualizerOptions } from './types'
+
+export function createSvelteVirtualizer(options: VirtualizerOptions) {
+  const virtualizer = createVirtualizer(options)
+  let version = $state(0)
+
+  virtualizer.subscribe(() => {
+    version += 1
+  })
+
+  return {
+    get version() {
+      return version
+    },
+    setOptions: virtualizer.setOptions,
+    setScrollOffset: virtualizer.setScrollOffset,
+    setViewportHeight: virtualizer.setViewportHeight,
+    scrollToIndex: virtualizer.scrollToIndex,
+    getVirtualItems: virtualizer.getVirtualItems,
+    getTotalSize: virtualizer.getTotalSize,
+    getState: virtualizer.getState,
+  }
+}

package/src/virtualization/types.ts

@@ -0,0 +1,30 @@
+export type VirtualItem = {
+  index: number
+  start: number
+  size: number
+  end: number
+  key: string
+}
+
+export type VirtualizerOptions = {
+  count: number
+  /**
+   * Per-item size. Pass a number for a uniform layout (fast path) or a
+   * function for variable sizing - the virtualizer will build cumulative
+   * offsets and use binary lookup to find the visible window. The function
+   * receives the item index and must return its pixel size.
+   */
+  estimateSize: number | ((index: number) => number)
+  overscan?: number
+  viewportHeight: number
+  scrollOffset?: number
+}
+
+export type VirtualizerState = {
+  items: Array<VirtualItem>
+  totalSize: number
+  startIndex: number
+  endIndex: number
+  scrollOffset: number
+  viewportHeight: number
+}

package/src/virtualization/virtualizer.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest'
+import { createVirtualizer } from './virtualizer'
+
+describe('virtualizer', () => {
+  it('computes bounded virtual range with overscan', () => {
+    const v = createVirtualizer({
+      count: 100_000,
+      estimateSize: 36,
+      overscan: 8,
+      viewportHeight: 360,
+      scrollOffset: 0,
+    })
+
+    const items = v.getVirtualItems()
+    expect(items.length).toBeGreaterThan(0)
+    expect(items[0]?.index).toBe(0)
+    expect(items[items.length - 1]?.index).toBe(18)
+  })
+
+  it('updates range when scroll offset changes', () => {
+    const v = createVirtualizer({
+      count: 100_000,
+      estimateSize: 40,
+      overscan: 5,
+      viewportHeight: 400,
+      scrollOffset: 0,
+    })
+
+    v.setScrollOffset(4_000)
+    const state = v.getState()
+    expect(state.startIndex).toBeLessThanOrEqual(100)
+    expect(state.endIndex).toBeGreaterThanOrEqual(110)
+  })
+
+  it('scrollToIndex clamps target offset', () => {
+    const v = createVirtualizer({
+      count: 100,
+      estimateSize: 30,
+      overscan: 2,
+      viewportHeight: 300,
+      scrollOffset: 0,
+    })
+
+    v.scrollToIndex(9_999)
+    expect(v.getState().scrollOffset).toBe(2_700)
+  })
+})