@svgrid/grid 1.0.0

package/src/index.ts

@@ -0,0 +1,159 @@
+export { formatNumericWithConfig, resolveDatePattern } from './cell-formatting'
+
+export {
+  columnFilteringFeature,
+  columnGroupingFeature,
+  createCoreRowModel,
+  createExpandedRowModel,
+  createFilteredRowModel,
+  createGroupedRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  applyGroupAggregate,
+  filterFns,
+  rowExpandingFeature,
+  rowPaginationFeature,
+  rowSelectionFeature,
+  rowSortingFeature,
+  sortFns,
+  tableFeatures,
+  type Cell,
+  type CellContext,
+  type EditorContext,
+  type CellData,
+  type ActiveCellState,
+  type CellFormatConfig,
+  type CellFormatter,
+  type Column,
+  type ColumnDef,
+  type ColumnDefTemplate,
+  type GroupAggregator,
+  type Header,
+  type HeaderContext,
+  type HeaderGroup,
+  type Row,
+  type RowData,
+  type SortingState,
+  type SvGrid as SvGridInstance,
+  type SvGridOptions,
+  type TableFeatures,
+  type Updater,
+} from './core'
+
+export { createGrid, createSvGrid, type SvelteGrid } from './createGrid.svelte'
+export { createGridState, createSvGridState } from './createGridState.svelte'
+export { subscribeGrid, subscribeSvGrid } from './subscribe'
+export { default as SvGrid } from './SvGrid.svelte'
+export { default as FlexRender } from './FlexRender.svelte'
+export { renderComponent, renderSnippet } from './render-component'
+export { default as SvGridChart } from './SvGridChart.svelte'
+export {
+  buildChart,
+  rowsToChartSpec,
+  niceScale,
+  DEFAULT_PALETTE,
+  type ChartType,
+  type ChartSpec,
+  type ChartSeries,
+  type ChartGeometry,
+  type ChartBar,
+  type ChartLine,
+  type ChartLinePoint,
+  type ChartPieSlice,
+  type ChartSelection,
+  type ChartReferenceLine,
+  type ChartRefLineGeo,
+  type ChartRefLineGeoV,
+  type ChartScatterDot,
+  type ScatterPoint,
+  type NiceScale,
+} from './chart'
+export {
+  chartToSvgString,
+  downloadChartSvg,
+  chartToPngBlob,
+  downloadChartPng,
+  type ChartExportOptions,
+} from './chart-export'
+export {
+  buildSparkline,
+  toSparklineValues,
+  type SparklineConfig,
+  type SparklineType,
+  type SparklineGeometry,
+} from './sparkline'
+export {
+  createCollaboration,
+  broadcastChannelTransport,
+  type CollabUser,
+  type CollabCell,
+  type CollabPresence,
+  type CollabMessage,
+  type CollabTransport,
+  type Collaboration,
+} from './collaboration'
+export {
+  createServerDataSource,
+  type ServerDataSource,
+  type ServerRequest,
+  type ServerResult,
+  type ServerController,
+  type ServerState,
+  type ServerSortModel,
+  type ServerFilterModel,
+} from './server-data-source'
+export {
+  createNamedViews,
+  memoryViews,
+  localStorageViews,
+  type SavedView,
+  type ViewStorage,
+  type NamedViews,
+} from './named-views'
+export {
+  resolveCellFormat,
+  computeColumnStat,
+  lerpColor,
+  contrastText,
+  type ConditionalFormat,
+  type ConditionalFormatSpec,
+  type ColorScaleFormat,
+  type DataBarFormat,
+  type IconSetFormat,
+  type RuleFormat,
+  type ResolvedCellFormat,
+} from './conditional-formatting'
+export { getKeyboardIntent, getNextActiveCell, type GridKeyboardIntent } from './keyboard'
+export { createVirtualizer } from './virtualization/virtualizer'
+export { createSvelteVirtualizer } from './virtualization/svelte-virtualizer.svelte'
+export { createColumnVirtualizer } from './virtualization/column-virtualizer'
+export type { VirtualItem, VirtualizerOptions, VirtualizerState } from './virtualization/types'
+export type { SvGridApi, SvGridFilterOperator, SvGridWrapperProps } from './svgrid-wrapper.types'
+export {
+  parseEditorValue,
+  normalizeEditorOptions,
+  type CellEditorType,
+  type CellEditorOption,
+} from './editors/cell-editors'
+export {
+  applyExcelFilter,
+  normalizeForFilter,
+  type ExcelFilter,
+  type ExcelFilterOperator,
+  type ExcelFilterOptions,
+} from './filtering/excel-filters'
+export {
+  getGridCellDomId,
+  getGridCellA11yProps,
+  getGridHeaderA11yProps,
+  getGridRootA11yProps,
+  getGridRowA11yProps,
+  type GridCellA11yInput,
+  type GridColumnA11yInput,
+  type GridSortDirection,
+} from './a11y'
+
+/**
+ * Compatibility alias for teams migrating from `createTable`.
+ */
+export { createSvGrid as createTable } from './createGrid.svelte'

package/src/keyboard.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+import { getKeyboardIntent, getNextActiveCell } from './keyboard'
+
+describe('keyboard navigation engine', () => {
+  it('maps keys to navigation intents', () => {
+    expect(getKeyboardIntent(new KeyboardEvent('keydown', { key: 'ArrowLeft' }))).toBe(
+      'moveLeft',
+    )
+    expect(getKeyboardIntent(new KeyboardEvent('keydown', { key: 'Home', ctrlKey: true }))).toBe(
+      'gridStart',
+    )
+    expect(getKeyboardIntent(new KeyboardEvent('keydown', { key: ' ' }))).toBe(
+      'activate',
+    )
+  })
+
+  it('computes next active cell within bounds', () => {
+    const next = getNextActiveCell(
+      { rowIndex: 1, colIndex: 1, cellId: null },
+      'moveDown',
+      { maxRow: 2, maxCol: 3, pageSize: 10 },
+    )
+    expect(next.rowIndex).toBe(2)
+    expect(next.colIndex).toBe(1)
+  })
+
+  it('handles row and grid boundary intents', () => {
+    const rowEnd = getNextActiveCell(
+      { rowIndex: 2, colIndex: 1, cellId: null },
+      'rowEnd',
+      { maxRow: 2, maxCol: 4, pageSize: 2 },
+    )
+    expect(rowEnd.colIndex).toBe(4)
+
+    const gridStart = getNextActiveCell(
+      { rowIndex: 2, colIndex: 4, cellId: null },
+      'gridStart',
+      { maxRow: 2, maxCol: 4, pageSize: 2 },
+    )
+    expect(gridStart.rowIndex).toBe(0)
+    expect(gridStart.colIndex).toBe(0)
+  })
+
+  it('clamps page navigation to valid bounds', () => {
+    const pageUp = getNextActiveCell(
+      { rowIndex: 1, colIndex: 0, cellId: null },
+      'pageUp',
+      { maxRow: 20, maxCol: 2, pageSize: 10 },
+    )
+    const pageDown = getNextActiveCell(
+      { rowIndex: 18, colIndex: 0, cellId: null },
+      'pageDown',
+      { maxRow: 20, maxCol: 2, pageSize: 10 },
+    )
+
+    expect(pageUp.rowIndex).toBe(0)
+    expect(pageDown.rowIndex).toBe(20)
+  })
+})

package/src/keyboard.ts

@@ -0,0 +1,97 @@
+import type { ActiveCellState } from './core'
+
+export type GridKeyboardIntent =
+  | 'moveLeft'
+  | 'moveRight'
+  | 'moveUp'
+  | 'moveDown'
+  | 'tabNext'
+  | 'tabPrev'
+  | 'rowStart'
+  | 'rowEnd'
+  | 'gridStart'
+  | 'gridEnd'
+  | 'pageUp'
+  | 'pageDown'
+  | 'activate'
+  | 'clearCells'
+  | 'noop'
+
+export function getKeyboardIntent(event: KeyboardEvent): GridKeyboardIntent {
+  // Ctrl+Home / Ctrl+End come before plain Home / End so the modifier wins.
+  if (event.ctrlKey && event.key === 'Home') return 'gridStart'
+  if (event.ctrlKey && event.key === 'End') return 'gridEnd'
+
+  if (event.key === 'ArrowLeft') return 'moveLeft'
+  if (event.key === 'ArrowRight') return 'moveRight'
+  if (event.key === 'ArrowUp') return 'moveUp'
+  if (event.key === 'ArrowDown') return 'moveDown'
+  if (event.key === 'Home') return 'rowStart'
+  if (event.key === 'End') return 'rowEnd'
+  if (event.key === 'PageUp') return 'pageUp'
+  if (event.key === 'PageDown') return 'pageDown'
+
+  // Excel-style data-entry navigation:
+  //   Enter      → move down (Shift+Enter → up)
+  //   Tab        → move right (Shift+Tab → left), wraps at row boundaries
+  //   Delete     → clear contents of the selected cells
+  //   F2 / Space → start editing the active cell
+  if (event.key === 'Enter') return event.shiftKey ? 'moveUp' : 'moveDown'
+  if (event.key === 'Tab') return event.shiftKey ? 'tabPrev' : 'tabNext'
+  if (event.key === 'F2') return 'activate'
+  if (event.key === ' ') return 'activate'
+  if (event.key === 'Delete') return 'clearCells'
+
+  return 'noop'
+}
+
+export function getNextActiveCell(
+  current: ActiveCellState,
+  intent: GridKeyboardIntent,
+  bounds: { maxRow: number; maxCol: number; pageSize?: number },
+): ActiveCellState {
+  const pageSize = bounds.pageSize ?? 10
+  let rowIndex = current.rowIndex
+  let colIndex = current.colIndex
+
+  if (intent === 'moveLeft') colIndex -= 1
+  if (intent === 'moveRight') colIndex += 1
+  if (intent === 'moveUp') rowIndex -= 1
+  if (intent === 'moveDown') rowIndex += 1
+  if (intent === 'tabNext') {
+    // Right one column; if we fall off the right edge, wrap to the
+    // first column of the next row - Excel's "data entry" behavior.
+    colIndex += 1
+    if (colIndex > bounds.maxCol) {
+      colIndex = 0
+      rowIndex += 1
+    }
+  }
+  if (intent === 'tabPrev') {
+    colIndex -= 1
+    if (colIndex < 0) {
+      colIndex = bounds.maxCol
+      rowIndex -= 1
+    }
+  }
+  if (intent === 'rowStart') colIndex = 0
+  if (intent === 'rowEnd') colIndex = bounds.maxCol
+  if (intent === 'gridStart') {
+    rowIndex = 0
+    colIndex = 0
+  }
+  if (intent === 'gridEnd') {
+    rowIndex = bounds.maxRow
+    colIndex = bounds.maxCol
+  }
+  if (intent === 'pageUp') rowIndex -= pageSize
+  if (intent === 'pageDown') rowIndex += pageSize
+
+  rowIndex = Math.min(Math.max(rowIndex, 0), Math.max(bounds.maxRow, 0))
+  colIndex = Math.min(Math.max(colIndex, 0), Math.max(bounds.maxCol, 0))
+  return {
+    rowIndex,
+    colIndex,
+    cellId: current.cellId,
+  }
+}

package/src/merge-objects.ts

@@ -0,0 +1,48 @@
+/**
+ * Merges objects together while keeping their getters alive.
+ * Taken from SolidJS:
+ * https://github.com/solidjs/solid/blob/24abc825c0996fd2bc8c1de1491efe9a7e743aff/packages/solid/src/server/rendering.ts#L82-L115
+ */
+export function mergeObjects<T>(source: T): T
+export function mergeObjects<T, U>(source: T, source1: U): T & U
+export function mergeObjects<T, U, V>(
+  source: T,
+  source1: U,
+  source2: V,
+): T & U & V
+export function mergeObjects<T, U, V, W>(
+  source: T,
+  source1: U,
+  source2: V,
+  source3: W,
+): T & U & V & W
+export function mergeObjects(...sources: any): any {
+  const target = {}
+
+  for (let source of sources) {
+    if (typeof source === 'function') source = source()
+
+    if (source) {
+      const descriptors = Object.getOwnPropertyDescriptors(source)
+
+      for (const key in descriptors) {
+        if (key in target) continue
+
+        Object.defineProperty(target, key, {
+          enumerable: true,
+          get() {
+            for (let i = sources.length - 1; i >= 0; i--) {
+              let scopedSource = sources[i]
+              if (typeof scopedSource === 'function') scopedSource = scopedSource()
+
+              const value = (scopedSource || {})[key]
+              if (value !== undefined) return value
+            }
+          },
+        })
+      }
+    }
+  }
+
+  return target
+}

package/src/named-views.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createNamedViews, memoryViews } from './named-views'
+import type { SvGridViewState } from './svgrid-wrapper.types'
+
+function fakeHost(initial: Partial<SvGridViewState> = {}) {
+  let state = { sorting: [], columnFilters: [], ...initial } as SvGridViewState
+  return {
+    getState: () => state,
+    setState: vi.fn((s: Partial<SvGridViewState>) => {
+      state = { ...state, ...s }
+    }),
+    _peek: () => state,
+  }
+}
+
+describe('createNamedViews', () => {
+  it('saves the current state and lists it', () => {
+    const host = fakeHost({ sorting: [{ id: 'name', desc: true }] })
+    const views = createNamedViews(host, { storage: memoryViews() })
+    views.save('By name')
+    expect(views.list().map((v) => v.name)).toEqual(['By name'])
+    expect(views.has('By name')).toBe(true)
+  })
+
+  it('load applies the saved state via setState', () => {
+    const host = fakeHost({ sorting: [{ id: 'age', desc: false }] })
+    const views = createNamedViews(host, { storage: memoryViews() })
+    views.save('snap')
+    host.setState({ sorting: [] }) // mutate away
+    host.setState.mockClear()
+    expect(views.load('snap')).toBe(true)
+    expect(host.setState).toHaveBeenCalledWith(
+      expect.objectContaining({ sorting: [{ id: 'age', desc: false }] }),
+    )
+    expect(views.load('missing')).toBe(false)
+  })
+
+  it('save overwrites a duplicate name but keeps its createdAt', () => {
+    const host = fakeHost()
+    const views = createNamedViews(host, { storage: memoryViews() })
+    const a = views.save('v')
+    const b = views.save('v')
+    expect(views.list()).toHaveLength(1)
+    expect(b.createdAt).toBe(a.createdAt)
+  })
+
+  it('remove and rename', () => {
+    const host = fakeHost()
+    const views = createNamedViews(host, { storage: memoryViews() })
+    views.save('a')
+    views.save('b')
+    expect(views.rename('a', 'c')).toBe(true)
+    expect(views.rename('c', 'b')).toBe(false) // target exists
+    expect(views.remove('c')).toBe(true)
+    expect(views.remove('c')).toBe(false)
+    expect(views.list().map((v) => v.name)).toEqual(['b'])
+  })
+
+  it('persists through a storage adapter', () => {
+    const store = memoryViews()
+    createNamedViews(fakeHost({ sorting: [{ id: 'x', desc: true }] }), { storage: store }).save('keep')
+    // A fresh manager over the same storage sees it.
+    const reopened = createNamedViews(fakeHost(), { storage: store })
+    expect(reopened.has('keep')).toBe(true)
+  })
+})

package/src/named-views.ts

@@ -0,0 +1,120 @@
+/**
+ * Named views. A thin, packaged manager on top of `api.getState()` /
+ * `api.setState()` so the "save / restore named layouts" feature every
+ * enterprise grid ships is one import instead of hand-rolled glue.
+ *
+ * Storage is pluggable: `localStorageViews(key)` persists per browser, or
+ * pass your own adapter to sync views to a server / per-user account. The
+ * manager itself is pure and synchronous, so it is trivially testable.
+ */
+import type { SvGridViewState } from './svgrid-wrapper.types'
+
+export type SavedView = {
+  name: string
+  state: Partial<SvGridViewState>
+  createdAt: number
+}
+
+export type ViewStorage = {
+  read(): SavedView[]
+  write(views: SavedView[]): void
+}
+
+/** Minimal grid handle the manager needs - `SvGridApi` satisfies it. */
+export type ViewStateHost = {
+  getState(): SvGridViewState
+  setState(state: Partial<SvGridViewState>): void
+}
+
+export type NamedViews = {
+  list(): SavedView[]
+  /** Capture the grid's current state under `name` (overwrites a duplicate). */
+  save(name: string): SavedView
+  /** Apply a saved view to the grid. Returns false if the name is unknown. */
+  load(name: string): boolean
+  /** Delete a saved view. Returns false if the name is unknown. */
+  remove(name: string): boolean
+  rename(from: string, to: string): boolean
+  has(name: string): boolean
+}
+
+/** In-memory storage (default). State lives only as long as the manager. */
+export function memoryViews(initial: SavedView[] = []): ViewStorage {
+  let views = [...initial]
+  return {
+    read: () => views,
+    write: (next) => {
+      views = next
+    },
+  }
+}
+
+/** localStorage-backed storage. Safe to construct in SSR (no-ops there). */
+export function localStorageViews(key: string): ViewStorage {
+  const available = typeof localStorage !== 'undefined'
+  return {
+    read() {
+      if (!available) return []
+      try {
+        const raw = localStorage.getItem(key)
+        const parsed = raw ? JSON.parse(raw) : []
+        return Array.isArray(parsed) ? (parsed as SavedView[]) : []
+      } catch {
+        return []
+      }
+    },
+    write(views) {
+      if (!available) return
+      try {
+        localStorage.setItem(key, JSON.stringify(views))
+      } catch {
+        /* quota / private mode - ignore */
+      }
+    },
+  }
+}
+
+export function createNamedViews(
+  host: ViewStateHost,
+  options: { storage?: ViewStorage } = {},
+): NamedViews {
+  const storage = options.storage ?? memoryViews()
+
+  const all = () => storage.read()
+  const find = (name: string) => all().find((v) => v.name === name)
+
+  return {
+    list: () => all().slice().sort((a, b) => a.createdAt - b.createdAt),
+    has: (name) => Boolean(find(name)),
+    save(name) {
+      const view: SavedView = {
+        name,
+        state: host.getState(),
+        createdAt: find(name)?.createdAt ?? Date.now(),
+      }
+      storage.write([...all().filter((v) => v.name !== name), view])
+      return view
+    },
+    load(name) {
+      const view = find(name)
+      if (!view) return false
+      host.setState(view.state)
+      return true
+    },
+    remove(name) {
+      const next = all().filter((v) => v.name !== name)
+      if (next.length === all().length) return false
+      storage.write(next)
+      return true
+    },
+    rename(from, to) {
+      const view = find(from)
+      if (!view || find(to)) return false
+      storage.write([
+        ...all().filter((v) => v.name !== from),
+        { ...view, name: to },
+      ])
+      return true
+    },
+  }
+}