@svgrid/grid 1.0.0

package/src/new-features.test.ts

@@ -0,0 +1,217 @@
+/**
+ * Tests for the headless-engine features shipped alongside the wrapper
+ * additions (`getRowId`, the `between` filter operator). Wrapper-level
+ * additions are covered by the source-level smoke tests in
+ * `svgrid.new-features.wrapper.test.ts` - jsdom + Svelte 5 mount is
+ * brittle for tests that only need to confirm props are read.
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  columnFilteringFeature,
+  createCoreRowModel,
+  createSvGrid,
+  rowSortingFeature,
+  tableFeatures,
+  type ColumnDef,
+} from './index'
+import { applyExcelFilter } from './filtering/excel-filters'
+
+type Row = { id: string; name: string; age: number }
+
+const data: Row[] = [
+  { id: 'ada',   name: 'Ada Lovelace',  age: 36 },
+  { id: 'linus', name: 'Linus Torvalds', age: 54 },
+  { id: 'grace', name: 'Grace Hopper',   age: 85 },
+]
+
+const columns: ColumnDef<{ rowSortingFeature: { key: string } }, Row>[] = [
+  { field: 'id',   header: 'ID' },
+  { field: 'name', header: 'Name' },
+  { field: 'age',  header: 'Age' },
+]
+
+const features = tableFeatures({ rowSortingFeature })
+
+describe('createSvGrid - getRowId', () => {
+  it('falls back to the array index as id when no getRowId is provided', () => {
+    const grid = createSvGrid({
+      _features: features,
+      _rowModels: { coreRowModel: createCoreRowModel<Row>() },
+      columns,
+      data,
+    })
+    const rows = grid.getRowModel().rows
+    expect(rows.map((r) => r.id)).toEqual(['0', '1', '2'])
+  })
+
+  it('uses the result of getRowId(row, index) as the row id', () => {
+    const grid = createSvGrid<typeof features, Row>({
+      _features: features,
+      _rowModels: { coreRowModel: createCoreRowModel<Row>() },
+      columns,
+      data,
+      getRowId: (row) => row.id,
+    })
+    const rows = grid.getRowModel().rows
+    expect(rows.map((r) => r.id)).toEqual(['ada', 'linus', 'grace'])
+  })
+
+  it('passes the row index to getRowId', () => {
+    const seen: Array<{ id: string; index: number }> = []
+    createSvGrid<typeof features, Row>({
+      _features: features,
+      _rowModels: { coreRowModel: createCoreRowModel<Row>() },
+      columns,
+      data,
+      getRowId: (row, index) => {
+        seen.push({ id: row.id, index })
+        return row.id
+      },
+    }).getRowModel().rows
+    expect(seen).toEqual([
+      { id: 'ada',   index: 0 },
+      { id: 'linus', index: 1 },
+      { id: 'grace', index: 2 },
+    ])
+  })
+
+  it('preserves the same id across `getRowModel()` invocations (stable identity)', () => {
+    const grid = createSvGrid<typeof features, Row>({
+      _features: features,
+      _rowModels: { coreRowModel: createCoreRowModel<Row>() },
+      columns,
+      data,
+      getRowId: (row) => `r:${row.id}`,
+    })
+    const first  = grid.getRowModel().rows.map((r) => r.id)
+    const second = grid.getRowModel().rows.map((r) => r.id)
+    expect(first).toEqual(second)
+    expect(first).toEqual(['r:ada', 'r:linus', 'r:grace'])
+  })
+})
+
+describe('applyExcelFilter - between operator', () => {
+  it('returns true when the value is inside the inclusive range', () => {
+    expect(applyExcelFilter(50, { id: 'age', operator: 'between', value: 18, valueTo: 65 })).toBe(true)
+  })
+
+  it('is inclusive at the lower bound', () => {
+    expect(applyExcelFilter(18, { id: 'age', operator: 'between', value: 18, valueTo: 65 })).toBe(true)
+  })
+
+  it('is inclusive at the upper bound', () => {
+    expect(applyExcelFilter(65, { id: 'age', operator: 'between', value: 18, valueTo: 65 })).toBe(true)
+  })
+
+  it('returns false when the value is below the range', () => {
+    expect(applyExcelFilter(17, { id: 'age', operator: 'between', value: 18, valueTo: 65 })).toBe(false)
+  })
+
+  it('returns false when the value is above the range', () => {
+    expect(applyExcelFilter(66, { id: 'age', operator: 'between', value: 18, valueTo: 65 })).toBe(false)
+  })
+
+  it('parses string endpoints as numbers (the wrapper hands strings through)', () => {
+    expect(applyExcelFilter('30', { id: 'age', operator: 'between', value: '18', valueTo: '65' })).toBe(true)
+  })
+
+  it('works with ISO date strings via lexicographic compare', () => {
+    expect(applyExcelFilter('2026-06-15', {
+      id: 'd', operator: 'between', value: '2026-01-01', valueTo: '2026-12-31',
+    })).toBe(true)
+    expect(applyExcelFilter('2025-12-31', {
+      id: 'd', operator: 'between', value: '2026-01-01', valueTo: '2026-12-31',
+    })).toBe(false)
+    expect(applyExcelFilter('2027-01-01', {
+      id: 'd', operator: 'between', value: '2026-01-01', valueTo: '2026-12-31',
+    })).toBe(false)
+  })
+})
+
+describe('ColumnDef.sortable + ColumnDef.filterable', () => {
+  const features = tableFeatures({
+    rowSortingFeature,
+    columnFilteringFeature,
+  })
+
+  function columnsWith(opts: {
+    nameSortable?: boolean
+    nameFilterable?: boolean
+    ageSortable?: boolean
+  }): ColumnDef<typeof features, Row>[] {
+    return [
+      { field: 'id',   header: 'ID' },
+      { field: 'name', header: 'Name', sortable: opts.nameSortable, filterable: opts.nameFilterable },
+      { field: 'age',  header: 'Age',  sortable: opts.ageSortable },
+    ]
+  }
+
+  it('getCanSort() returns true by default when rowSortingFeature is on', () => {
+    const grid = createSvGrid({
+      _features: features,
+      _rowModels: { coreRowModel: createCoreRowModel<Row>() },
+      data,
+      columns: columnsWith({}),
+    })
+    const name = grid.getAllColumns().find((c) => c.id === 'name')
+    expect(name?.getCanSort()).toBe(true)
+  })
+
+  it('getCanSort() returns false when columnDef.sortable === false', () => {
+    const grid = createSvGrid({
+      _features: features,
+      _rowModels: { coreRowModel: createCoreRowModel<Row>() },
+      data,
+      columns: columnsWith({ nameSortable: false }),
+    })
+    const name = grid.getAllColumns().find((c) => c.id === 'name')
+    const age  = grid.getAllColumns().find((c) => c.id === 'age')
+    expect(name?.getCanSort()).toBe(false)
+    expect(age?.getCanSort()).toBe(true)
+  })
+
+  it('getCanSort() still returns false even with sortable: true if the feature is OFF', () => {
+    const noSortFeatures = tableFeatures({ columnFilteringFeature })
+    const grid = createSvGrid({
+      _features: noSortFeatures,
+      _rowModels: { coreRowModel: createCoreRowModel<Row>() },
+      data,
+      columns: [
+        { field: 'name', header: 'Name', sortable: true },
+      ] as ColumnDef<typeof noSortFeatures, Row>[],
+    })
+    const name = grid.getAllColumns().find((c) => c.id === 'name')
+    expect(name?.getCanSort()).toBe(false)
+  })
+
+  it('getCanFilter() returns false when columnDef.filterable === false', () => {
+    const grid = createSvGrid({
+      _features: features,
+      _rowModels: { coreRowModel: createCoreRowModel<Row>() },
+      data,
+      columns: columnsWith({ nameFilterable: false }),
+    })
+    const name = grid.getAllColumns().find((c) => c.id === 'name')
+    const age  = grid.getAllColumns().find((c) => c.id === 'age')
+    expect(name?.getCanFilter()).toBe(false)
+    expect(age?.getCanFilter()).toBe(true)
+  })
+
+  it('sortable + filterable are independent', () => {
+    const grid = createSvGrid({
+      _features: features,
+      _rowModels: { coreRowModel: createCoreRowModel<Row>() },
+      data,
+      columns: [
+        { field: 'name', header: 'Name', sortable: false, filterable: true },
+        { field: 'age',  header: 'Age',  sortable: true,  filterable: false },
+      ] as ColumnDef<typeof features, Row>[],
+    })
+    const name = grid.getAllColumns().find((c) => c.id === 'name')
+    const age  = grid.getAllColumns().find((c) => c.id === 'age')
+    expect(name?.getCanSort()).toBe(false)
+    expect(name?.getCanFilter()).toBe(true)
+    expect(age?.getCanSort()).toBe(true)
+    expect(age?.getCanFilter()).toBe(false)
+  })
+})

package/src/render-component.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Unit tests for the renderComponent / renderSnippet factories.
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  RenderComponentConfig,
+  RenderSnippetConfig,
+  renderComponent,
+  renderSnippet,
+} from './render-component'
+
+describe('renderComponent', () => {
+  it('returns a RenderComponentConfig instance', () => {
+    const FakeComponent = (() => null) as any
+    const config = renderComponent(FakeComponent)
+    expect(config).toBeInstanceOf(RenderComponentConfig)
+    expect(config.component).toBe(FakeComponent)
+    expect(config.props).toBeUndefined()
+  })
+
+  it('captures the props payload as-is', () => {
+    const FakeComponent = (() => null) as any
+    const config = renderComponent(FakeComponent, { id: 1, label: 'Hello' } as any)
+    expect(config.props).toEqual({ id: 1, label: 'Hello' })
+  })
+
+  it('reuses the constructor instance fields', () => {
+    const FakeComponent = (() => null) as any
+    const a = renderComponent(FakeComponent, { x: 1 } as any)
+    const b = renderComponent(FakeComponent, { x: 1 } as any)
+    // Different instances - the factory does not memoize.
+    expect(a).not.toBe(b)
+    expect(a.component).toBe(b.component)
+  })
+})
+
+describe('renderSnippet', () => {
+  it('returns a RenderSnippetConfig instance with the captured snippet + params', () => {
+    const fakeSnippet = (() => null) as any
+    const config = renderSnippet(fakeSnippet, { value: 42 })
+    expect(config).toBeInstanceOf(RenderSnippetConfig)
+    expect(config.snippet).toBe(fakeSnippet)
+    expect(config.params).toEqual({ value: 42 })
+  })
+
+  it('allows an undefined params payload', () => {
+    const fakeSnippet = (() => null) as any
+    const config = renderSnippet(fakeSnippet)
+    expect(config.params).toBeUndefined()
+  })
+})

package/src/render-component.ts

@@ -0,0 +1,28 @@
+import type { Component, ComponentProps, Snippet } from 'svelte'
+
+export class RenderComponentConfig<TComponent extends Component> {
+  constructor(
+    public component: TComponent,
+    public props?: ComponentProps<TComponent> | Record<string, never>,
+  ) {}
+}
+
+export class RenderSnippetConfig<TProps> {
+  constructor(
+    public snippet: Snippet<[TProps]>,
+    public params?: TProps,
+  ) {}
+}
+
+export const renderComponent = <
+  TComponent extends Component<any>,
+  TProps extends ComponentProps<TComponent>,
+>(
+  component: TComponent,
+  props?: TProps,
+) => new RenderComponentConfig(component, props)
+
+export const renderSnippet = <TProps>(
+  snippet: Snippet<[TProps]>,
+  params?: TProps,
+) => new RenderSnippetConfig(snippet, params)

package/src/server-data-source.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createServerDataSource, type ServerDataSource } from './server-data-source'
+
+type Row = { id: number }
+
+function makeSource(total = 250, delay = 0): ServerDataSource<Row> & { calls: number } {
+  const all: Row[] = Array.from({ length: total }, (_, i) => ({ id: i }))
+  return {
+    calls: 0,
+    async getRows(req) {
+      this.calls += 1
+      if (delay) await new Promise((r) => setTimeout(r, delay))
+      // server applies sort: reverse when desc on 'id'
+      let rows = all
+      if (req.sortModel[0]?.id === 'id' && req.sortModel[0]?.desc) rows = [...all].reverse()
+      return { rows: rows.slice(req.startRow, req.endRow), rowCount: total }
+    },
+  }
+}
+
+const flush = () => new Promise((r) => setTimeout(r, 0))
+
+describe('createServerDataSource', () => {
+  it('fetches a page and reports total + pageCount', async () => {
+    const src = makeSource(250)
+    const states: any[] = []
+    const ctl = createServerDataSource(src, { pageSize: 50, onChange: (s) => states.push(s) })
+    ctl.refresh()
+    await flush()
+    const last = ctl.getState()
+    expect(last.rows).toHaveLength(50)
+    expect(last.total).toBe(250)
+    expect(last.pageCount).toBe(5)
+    expect(last.loading).toBe(false)
+    // emitted a loading=true then loading=false
+    expect(states.some((s) => s.loading)).toBe(true)
+  })
+
+  it('setPage fetches the right slice', async () => {
+    const src = makeSource(250)
+    const ctl = createServerDataSource(src, { pageSize: 50, onChange: () => {} })
+    ctl.setPage(2)
+    await flush()
+    expect(ctl.getState().rows[0]).toEqual({ id: 100 })
+  })
+
+  it('setSort resets to page 0 and re-fetches', async () => {
+    const src = makeSource(250)
+    const ctl = createServerDataSource(src, { pageSize: 50, onChange: () => {} })
+    ctl.setPage(2)
+    await flush()
+    ctl.setSort([{ id: 'id', desc: true }])
+    await flush()
+    const s = ctl.getState()
+    expect(s.pageIndex).toBe(0)
+    expect(s.rows[0]).toEqual({ id: 249 }) // reversed
+  })
+
+  it('ignores a stale response when a newer request supersedes it', async () => {
+    // slow source: first call (page 0) resolves AFTER the second (page 1)
+    const all = Array.from({ length: 100 }, (_, i) => ({ id: i }))
+    let call = 0
+    const src: ServerDataSource<Row> = {
+      getRows: vi.fn(async (req) => {
+        call += 1
+        const delay = call === 1 ? 40 : 5 // first call is slow
+        await new Promise((r) => setTimeout(r, delay))
+        return { rows: all.slice(req.startRow, req.endRow), rowCount: 100 }
+      }),
+    }
+    const ctl = createServerDataSource(src, { pageSize: 10, onChange: () => {} })
+    ctl.refresh() // page 0 (slow)
+    ctl.setPage(3) // page 30 (fast) - should win
+    await new Promise((r) => setTimeout(r, 80))
+    expect(ctl.getState().rows[0]).toEqual({ id: 30 })
+  })
+
+  it('dispose stops further updates', async () => {
+    const src = makeSource(50, 20)
+    const onChange = vi.fn()
+    const ctl = createServerDataSource(src, { pageSize: 10, onChange })
+    ctl.refresh()
+    ctl.dispose()
+    await new Promise((r) => setTimeout(r, 40))
+    // only the synchronous loading=true emit happened before dispose
+    expect(ctl.getState().rows).toHaveLength(0)
+  })
+})

package/src/server-data-source.ts

@@ -0,0 +1,163 @@
+/**
+ * Server-Side Row Model (SSRM) controller. A single, documented datasource
+ * contract for grids whose data lives on the server - the "I have a million
+ * rows in a database" case. The consumer implements ONE async `getRows`
+ * function; this controller owns the request lifecycle (sort, filter, page),
+ * de-dupes/races, and pushes results back through `onChange`.
+ *
+ * It's headless and framework-agnostic on purpose: wire `setSort` /
+ * `setFilter` / `setPage` to the grid's controlled callbacks, and render the
+ * grid from the `{ rows, total, loading }` it hands you. See the demo.
+ */
+export type ServerSortModel = Array<{ id: string; desc: boolean }>
+
+export type ServerFilterModel = {
+  /** Free-text global search. */
+  global?: string
+  /**
+   * Per-column filters, keyed by column id. `value` (+ `valueTo`) carry the
+   * operator-style filter; `selectedValues` carries a facet/checklist
+   * selection (set-filter). Either or both may be present.
+   */
+  columns?: Record<
+    string,
+    { operator: string; value: string; valueTo?: string; selectedValues?: string[] }
+  >
+}
+
+export type ServerRequest = {
+  /** Zero-based index of the first row wanted (inclusive). */
+  startRow: number
+  /** Index just past the last row wanted (exclusive). */
+  endRow: number
+  pageIndex: number
+  pageSize: number
+  sortModel: ServerSortModel
+  filterModel: ServerFilterModel
+}
+
+export type ServerResult<TData> = {
+  rows: ReadonlyArray<TData>
+  /** Total row count after filtering (for the pager). */
+  rowCount: number
+}
+
+export type ServerDataSource<TData> = {
+  getRows(request: ServerRequest): Promise<ServerResult<TData>>
+}
+
+export type ServerState<TData> = {
+  rows: ReadonlyArray<TData>
+  total: number
+  loading: boolean
+  error: unknown
+  pageIndex: number
+  pageSize: number
+  pageCount: number
+  sortModel: ServerSortModel
+  filterModel: ServerFilterModel
+}
+
+export type ServerController<TData> = {
+  /** Re-fetch the current page (e.g. after a mutation). */
+  refresh(): void
+  setSort(sortModel: ServerSortModel): void
+  setFilter(filterModel: ServerFilterModel): void
+  setPage(pageIndex: number): void
+  setPageSize(pageSize: number): void
+  getState(): ServerState<TData>
+  /** Stop accepting in-flight responses (call on unmount). */
+  dispose(): void
+}
+
+export type ServerControllerOptions<TData> = {
+  pageSize?: number
+  /** Called whenever any of `rows` / `total` / `loading` / page changes. */
+  onChange: (state: ServerState<TData>) => void
+}
+
+export function createServerDataSource<TData>(
+  source: ServerDataSource<TData>,
+  options: ServerControllerOptions<TData>,
+): ServerController<TData> {
+  const state: ServerState<TData> = {
+    rows: [],
+    total: 0,
+    loading: false,
+    error: null,
+    pageIndex: 0,
+    pageSize: options.pageSize ?? 50,
+    pageCount: 1,
+    sortModel: [],
+    filterModel: {},
+  }
+
+  // Monotonic request id: only the latest fetch is allowed to land, so a slow
+  // response for an old sort/filter can't clobber a newer one.
+  let requestSeq = 0
+  let disposed = false
+
+  const emit = () => {
+    state.pageCount = Math.max(1, Math.ceil(state.total / state.pageSize))
+    options.onChange({ ...state })
+  }
+
+  async function fetchPage() {
+    if (disposed) return
+    const id = ++requestSeq
+    state.loading = true
+    state.error = null
+    emit()
+    const startRow = state.pageIndex * state.pageSize
+    try {
+      const result = await source.getRows({
+        startRow,
+        endRow: startRow + state.pageSize,
+        pageIndex: state.pageIndex,
+        pageSize: state.pageSize,
+        sortModel: state.sortModel,
+        filterModel: state.filterModel,
+      })
+      if (disposed || id !== requestSeq) return // stale
+      state.rows = result.rows
+      state.total = result.rowCount
+      state.loading = false
+      emit()
+    } catch (err) {
+      if (disposed || id !== requestSeq) return
+      state.rows = []
+      state.error = err
+      state.loading = false
+      emit()
+    }
+  }
+
+  return {
+    refresh: fetchPage,
+    setSort(sortModel) {
+      state.sortModel = sortModel
+      state.pageIndex = 0
+      void fetchPage()
+    },
+    setFilter(filterModel) {
+      state.filterModel = filterModel
+      state.pageIndex = 0
+      void fetchPage()
+    },
+    setPage(pageIndex) {
+      const clamped = Math.max(0, pageIndex)
+      if (clamped === state.pageIndex) return
+      state.pageIndex = clamped
+      void fetchPage()
+    },
+    setPageSize(pageSize) {
+      state.pageSize = Math.max(1, pageSize)
+      state.pageIndex = 0
+      void fetchPage()
+    },
+    getState: () => ({ ...state }),
+    dispose() {
+      disposed = true
+    },
+  }
+}

package/src/sparkline.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+import { buildSparkline, toSparklineValues } from './sparkline'
+
+describe('toSparklineValues', () => {
+  it('passes through number arrays and drops non-finite', () => {
+    expect(toSparklineValues([1, 2, NaN, 3])).toEqual([1, 2, 3])
+  })
+  it('parses comma / space separated strings', () => {
+    expect(toSparklineValues('1, 2 3,4')).toEqual([1, 2, 3, 4])
+  })
+  it('returns [] for empty / unusable input', () => {
+    expect(toSparklineValues(null)).toEqual([])
+    expect(toSparklineValues('')).toEqual([])
+    expect(toSparklineValues({})).toEqual([])
+  })
+})
+
+describe('buildSparkline', () => {
+  it('returns null for empty data', () => {
+    expect(buildSparkline([])).toBeNull()
+  })
+
+  it('builds a line path through every point', () => {
+    const g = buildSparkline([0, 5, 10], { type: 'line', width: 100, height: 20 })!
+    expect(g.type).toBe('line')
+    expect(g.linePath.startsWith('M')).toBe(true)
+    // three points => one M + two L commands
+    expect((g.linePath.match(/[ML]/g) ?? []).length).toBe(3)
+    expect(g.lastPoint).not.toBeNull()
+  })
+
+  it('closes the area path back to the baseline', () => {
+    const g = buildSparkline([1, 2, 3], { type: 'area' })!
+    expect(g.areaPath.endsWith('Z')).toBe(true)
+  })
+
+  it('emits one bar per value and flags negatives', () => {
+    const g = buildSparkline([-2, 4, -1], { type: 'bar' })!
+    expect(g.bars).toHaveLength(3)
+    expect(g.bars[0]!.negative).toBe(true)
+    expect(g.bars[1]!.negative).toBe(false)
+  })
+
+  it('winloss uses sign only, equal-height up/down bars', () => {
+    const g = buildSparkline([1, -1, 1], { type: 'winloss', height: 20 })!
+    expect(g.bars).toHaveLength(3)
+    expect(g.bars[0]!.negative).toBe(false)
+    expect(g.bars[1]!.negative).toBe(true)
+    // up and down bars are the same height (sign-only chart)
+    expect(g.bars[0]!.h).toBeCloseTo(g.bars[1]!.h)
+  })
+
+  it('honors a fixed min/max scale', () => {
+    const a = buildSparkline([5, 5, 5], { type: 'line', min: 0, max: 10 })!
+    // flat series on a 0..10 scale sits at the vertical middle, not the top
+    const ys = a.linePath.match(/,(-?\d+(\.\d+)?)/g)!.map((s) => Number(s.slice(1)))
+    expect(new Set(ys).size).toBe(1)
+  })
+})