@tipolox/litgrid-core 1.0.3 → 1.1.0

package/README.md

@@ -13,6 +13,7 @@ npm install @tipolox/litgrid-core
 - [Core engine API](https://github.com/tipolox/litgrid/blob/main/docs/api-reference.md#core-engine)
 - [Installation guide](https://github.com/tipolox/litgrid/blob/main/docs/installation.md)
 - [Repository](https://github.com/tipolox/litgrid)
+- [v1.1.0 upgrade guide](https://github.com/tipolox/litgrid/blob/main/docs/installation.md#upgrading-to-v110)
 - [Live demo](https://tipolox.com/litgrid/demo)
 
 Licensed under the [MIT License](https://github.com/tipolox/litgrid/blob/main/LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tipolox/litgrid-core",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Framework-agnostic data engine for LitGrid.",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,7 +15,11 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "src/**/*.ts",
+    "!src/**/*.d.ts",
+    "!src/**/*.test.ts",
+    "!src/**/*.bench.ts"
   ],
   "keywords": [
     "data-grid",

package/src/core/GridEngine.ts

@@ -0,0 +1,38 @@
+import type { GridConfig, ResolvedGridConfig } from '../model/GridConfig.js'
+import type {
+  GridSelection,
+  GridFilter,
+  GridPaginationState,
+  GridSortState,
+  SelectionIntent,
+  SortDirection
+} from '../model/GridState.js'
+
+export type GridEngine = {
+  setConfig: (config: GridConfig) => void
+  getConfig: () => ResolvedGridConfig
+  setData: (data: unknown[]) => void
+  getRows: () => unknown[]
+  setQuickSearch: (query: string) => void
+  clearQuickSearch: () => void
+  getQuickSearch: () => string
+  setFilter: (filter: GridFilter) => void
+  clearFilter: (columnKey?: string) => void
+  getFilters: () => GridFilter[]
+  setPage: (pageIndex: number) => void
+  setPageSize: (pageSize: number) => void
+  getPagination: () => GridPaginationState
+  getTotalRowCount: () => number
+  sortBy: (columnKey: string, direction: SortDirection) => void
+  clearSort: () => void
+  getSort: () => GridSortState
+  getRowCount: () => number
+  getVisibleRows: (startIndex: number, endIndex: number) => unknown[]
+  selectRow: (rowIndex: number, intent?: SelectionIntent) => void
+  selectAllRows: () => void
+  selectCell: (rowIndex: number, columnKey: string) => void
+  clearSelection: () => void
+  getSelection: () => GridSelection
+  isRowSelected: (rowIndex: number) => boolean
+  isCellSelected: (rowIndex: number, columnKey: string) => boolean
+}

package/src/core/createGridEngine.ts

@@ -0,0 +1,217 @@
+import type { GridConfig } from '../model/GridConfig.js'
+import { normalizeConfig } from '../model/GridConfig.js'
+import type { GridFilter, GridState, SelectionIntent, SortDirection } from '../model/GridState.js'
+import {
+  createEmptySelection,
+  getCellKey,
+  getNextCellSelection,
+  getNextRowSelection
+} from '../features/selection/selection.js'
+import { applyDataTransforms } from '../features/transforms/applyDataTransforms.js'
+import { clampPageIndex, createPaginationState, paginateData } from '../features/pagination/pagination.js'
+import type { GridEngine } from './GridEngine.js'
+
+export function createGridEngine(config: GridConfig = {}): GridEngine {
+  const initialConfig = normalizeConfig(config)
+  let state: GridState = {
+    config: initialConfig,
+    originalData: [],
+    transformedData: [],
+    data: [],
+    sort: { columnKey: null, direction: null },
+    quickSearchQuery: '',
+    filters: [],
+    pagination: createPaginationState(
+      initialConfig.pagination.enabled,
+      initialConfig.pagination.pageSize,
+      initialConfig.pagination.pageIndex
+    ),
+    selection: createEmptySelection(initialConfig.selection.mode)
+  }
+
+  function refreshData() {
+    state.transformedData = applyDataTransforms(
+      state.originalData,
+      state.quickSearchQuery,
+      state.filters,
+      state.sort
+    )
+    const pageCount = Math.ceil(state.transformedData.length / state.pagination.pageSize)
+    state.pagination = {
+      ...state.pagination,
+      totalRows: state.transformedData.length,
+      pageCount,
+      pageIndex: clampPageIndex(state.pagination.pageIndex, pageCount)
+    }
+    state.data = paginateData(state.transformedData, state.pagination)
+  }
+
+  function resetPage() {
+    state.pagination = { ...state.pagination, pageIndex: 0 }
+  }
+
+  return {
+    setConfig(config: GridConfig) {
+      const nextConfig = normalizeConfig(config)
+
+      state.config = nextConfig
+      state.pagination = createPaginationState(
+        nextConfig.pagination.enabled,
+        nextConfig.pagination.pageSize,
+        nextConfig.pagination.pageIndex,
+        state.transformedData.length
+      )
+      refreshData()
+
+      if (state.selection.mode !== nextConfig.selection.mode) {
+        state.selection = createEmptySelection(nextConfig.selection.mode)
+      }
+    },
+    getConfig() {
+      return state.config
+    },
+    setData(data: unknown[]) {
+      state.originalData = data ?? []
+      resetPage()
+      refreshData()
+    },
+    getRows() {
+      return state.data
+    },
+    setQuickSearch(query: string) {
+      state.quickSearchQuery = typeof query === 'string' ? query : ''
+      resetPage()
+      refreshData()
+    },
+    clearQuickSearch() {
+      state.quickSearchQuery = ''
+      resetPage()
+      refreshData()
+    },
+    getQuickSearch() {
+      return state.quickSearchQuery
+    },
+    setFilter(filter: GridFilter) {
+      state.filters = [
+        ...state.filters.filter((item) => item.columnKey !== filter.columnKey),
+        { ...filter }
+      ]
+      resetPage()
+      refreshData()
+    },
+    clearFilter(columnKey?: string) {
+      state.filters = columnKey
+        ? state.filters.filter((item) => item.columnKey !== columnKey)
+        : []
+      resetPage()
+      refreshData()
+    },
+    getFilters() {
+      return state.filters.slice()
+    },
+    setPage(pageIndex: number) {
+      const nextPageIndex = Number.isFinite(pageIndex) ? Math.max(0, Math.floor(pageIndex)) : 0
+      state.pagination = {
+        ...state.pagination,
+        pageIndex: clampPageIndex(nextPageIndex, state.pagination.pageCount)
+      }
+      state.data = paginateData(state.transformedData, state.pagination)
+    },
+    setPageSize(pageSize: number) {
+      if (!Number.isFinite(pageSize) || pageSize <= 0) {
+        return
+      }
+
+      state.pagination = {
+        ...state.pagination,
+        pageSize: Math.max(1, Math.floor(pageSize)),
+        pageIndex: 0
+      }
+      refreshData()
+    },
+    getPagination() {
+      return { ...state.pagination }
+    },
+    getTotalRowCount() {
+      return state.pagination.totalRows
+    },
+    sortBy(columnKey: string, direction: SortDirection) {
+      state.sort = { columnKey, direction }
+      resetPage()
+      refreshData()
+    },
+    clearSort() {
+      state.sort = { columnKey: null, direction: null }
+      resetPage()
+      refreshData()
+    },
+    getSort() {
+      return state.sort
+    },
+    getRowCount() {
+      return state.data.length
+    },
+    getVisibleRows(startIndex: number, endIndex: number) {
+      return state.data.slice(startIndex, endIndex)
+    },
+    selectRow(rowIndex: number, intent: SelectionIntent = 'replace') {
+      const nextSelection = getNextRowSelection(
+        state.selection,
+        state.config.selection.mode,
+        rowIndex,
+        intent
+      )
+
+      if (nextSelection) {
+        state.selection = nextSelection
+      }
+    },
+    selectAllRows() {
+      if (state.config.selection.mode !== 'multi-row') {
+        return
+      }
+
+      const rowIndexes = new Set<number>()
+      for (let rowIndex = 0; rowIndex < state.data.length; rowIndex += 1) {
+        rowIndexes.add(rowIndex)
+      }
+
+      state.selection = {
+        ...createEmptySelection('multi-row'),
+        rowIndex: state.data.length > 0 ? state.data.length - 1 : null,
+        anchorRowIndex: state.data.length > 0 ? 0 : null,
+        rowIndexes
+      }
+    },
+    selectCell(rowIndex: number, columnKey: string) {
+      const nextSelection = getNextCellSelection(
+        state.selection,
+        state.config.selection.mode,
+        rowIndex,
+        columnKey
+      )
+
+      if (nextSelection) {
+        state.selection = nextSelection
+      }
+    },
+    clearSelection() {
+      state.selection = createEmptySelection(state.config.selection.mode)
+    },
+    getSelection() {
+      return state.selection
+    },
+    isRowSelected(rowIndex: number) {
+      return (
+        (state.selection.mode === 'row' || state.selection.mode === 'multi-row') &&
+        state.selection.rowIndexes.has(rowIndex)
+      )
+    },
+    isCellSelected(rowIndex: number, columnKey: string) {
+      return (
+        (state.selection.mode === 'cell' || state.selection.mode === 'multi-cell') &&
+        state.selection.cells.has(getCellKey(rowIndex, columnKey))
+      )
+    }
+  }
+}

package/src/features/filtering/filtering.ts

@@ -0,0 +1,63 @@
+import type { GridFilter } from '../../model/GridState.js'
+
+function getRowFilterValue(row: unknown, columnKey: string) {
+  if (row && typeof row === 'object' && !Array.isArray(row) && columnKey in row) {
+    return (row as Record<string, unknown>)[columnKey]
+  }
+
+  return row
+}
+
+function isEmpty(value: unknown) {
+  return value === null || value === undefined || value === ''
+}
+
+function normalizeText(value: unknown) {
+  return String(value ?? '').toLocaleLowerCase()
+}
+
+function compareValues(left: unknown, right: unknown) {
+  if (typeof left === 'number') {
+    const numericRight = typeof right === 'number' ? right : Number(right)
+    if (!Number.isNaN(numericRight)) {
+      return left - numericRight
+    }
+  }
+
+  return normalizeText(left).localeCompare(normalizeText(right))
+}
+
+function matchesFilter(value: unknown, filter: GridFilter) {
+  switch (filter.operator) {
+    case 'isEmpty':
+      return isEmpty(value)
+    case 'isNotEmpty':
+      return !isEmpty(value)
+    case 'contains':
+      return normalizeText(value).includes(normalizeText(filter.value))
+    case 'equals':
+      return compareValues(value, filter.value) === 0
+    case 'startsWith':
+      return normalizeText(value).startsWith(normalizeText(filter.value))
+    case 'endsWith':
+      return normalizeText(value).endsWith(normalizeText(filter.value))
+    case 'greaterThan':
+      return compareValues(value, filter.value) > 0
+    case 'greaterThanOrEqual':
+      return compareValues(value, filter.value) >= 0
+    case 'lessThan':
+      return compareValues(value, filter.value) < 0
+    case 'lessThanOrEqual':
+      return compareValues(value, filter.value) <= 0
+  }
+}
+
+export function applyFilterData(data: unknown[], filters: GridFilter[]) {
+  if (filters.length === 0) {
+    return data.slice()
+  }
+
+  return data.filter((row) =>
+    filters.every((filter) => matchesFilter(getRowFilterValue(row, filter.columnKey), filter))
+  )
+}

package/src/features/pagination/pagination.ts

@@ -0,0 +1,35 @@
+import type { GridPaginationState } from '../../model/GridState.js'
+
+export function getPageCount(totalRows: number, pageSize: number) {
+  return totalRows === 0 ? 0 : Math.ceil(totalRows / pageSize)
+}
+
+export function clampPageIndex(pageIndex: number, pageCount: number) {
+  return pageCount === 0 ? 0 : Math.min(Math.max(0, pageIndex), pageCount - 1)
+}
+
+export function createPaginationState(
+  enabled: boolean,
+  pageSize: number,
+  pageIndex = 0,
+  totalRows = 0
+): GridPaginationState {
+  const pageCount = getPageCount(totalRows, pageSize)
+
+  return {
+    enabled,
+    pageSize,
+    pageIndex: clampPageIndex(pageIndex, pageCount),
+    totalRows,
+    pageCount
+  }
+}
+
+export function paginateData(data: unknown[], pagination: GridPaginationState) {
+  if (!pagination.enabled) {
+    return data
+  }
+
+  const start = pagination.pageIndex * pagination.pageSize
+  return data.slice(start, start + pagination.pageSize)
+}

package/src/features/quick-search/quickSearch.ts

@@ -0,0 +1,31 @@
+function normalizeQuery(query: string) {
+  return query.trim().toLocaleLowerCase()
+}
+
+function matchesValue(value: unknown, query: string) {
+  return (
+    (typeof value === 'string' ||
+      typeof value === 'number' ||
+      typeof value === 'boolean' ||
+      typeof value === 'bigint') &&
+    String(value).toLocaleLowerCase().includes(query)
+  )
+}
+
+function matchesRow(row: unknown, query: string) {
+  if (row && typeof row === 'object' && !Array.isArray(row)) {
+    return Object.values(row as Record<string, unknown>).some((value) => matchesValue(value, query))
+  }
+
+  return matchesValue(row, query)
+}
+
+export function applyQuickSearch(data: unknown[], query: string) {
+  const normalizedQuery = normalizeQuery(query)
+
+  if (!normalizedQuery) {
+    return data.slice()
+  }
+
+  return data.filter((row) => matchesRow(row, normalizedQuery))
+}

package/src/features/selection/selection.ts

@@ -0,0 +1,111 @@
+import type { SelectionMode } from '../../model/GridConfig.js'
+import type { GridSelection, SelectionIntent } from '../../model/GridState.js'
+import { getRowRange } from '../../utils/range.js'
+
+export function createEmptySelection(mode: SelectionMode): GridSelection {
+  return {
+    mode,
+    rowIndex: null,
+    columnKey: null,
+    anchorRowIndex: null,
+    rowIndexes: new Set(),
+    cells: new Set()
+  }
+}
+
+export function getCellKey(rowIndex: number, columnKey: string) {
+  return `${rowIndex}:${columnKey}`
+}
+
+export function getNextRowSelection(
+  selection: GridSelection,
+  mode: SelectionMode,
+  rowIndex: number,
+  intent: SelectionIntent
+): GridSelection | null {
+  if (mode === 'row') {
+    return {
+      ...createEmptySelection('row'),
+      rowIndex,
+      anchorRowIndex: rowIndex,
+      rowIndexes: new Set([rowIndex])
+    }
+  }
+
+  if (mode !== 'multi-row') {
+    return null
+  }
+
+  if (intent === 'range') {
+    const anchorRowIndex = selection.anchorRowIndex ?? rowIndex
+
+    return {
+      ...createEmptySelection('multi-row'),
+      rowIndex,
+      anchorRowIndex,
+      rowIndexes: getRowRange(anchorRowIndex, rowIndex)
+    }
+  }
+
+  if (intent === 'toggle') {
+    const rowIndexes = new Set(selection.rowIndexes)
+
+    if (rowIndexes.has(rowIndex)) {
+      rowIndexes.delete(rowIndex)
+    } else {
+      rowIndexes.add(rowIndex)
+    }
+
+    return {
+      ...createEmptySelection('multi-row'),
+      rowIndex: rowIndexes.has(rowIndex) ? rowIndex : null,
+      anchorRowIndex: rowIndex,
+      rowIndexes
+    }
+  }
+
+  return {
+    ...createEmptySelection('multi-row'),
+    rowIndex,
+    anchorRowIndex: rowIndex,
+    rowIndexes: new Set([rowIndex])
+  }
+}
+
+export function getNextCellSelection(
+  selection: GridSelection,
+  mode: SelectionMode,
+  rowIndex: number,
+  columnKey: string
+): GridSelection | null {
+  if (mode === 'cell') {
+    return {
+      ...createEmptySelection('cell'),
+      rowIndex,
+      columnKey,
+      cells: new Set([getCellKey(rowIndex, columnKey)])
+    }
+  }
+
+  if (mode !== 'multi-cell') {
+    return null
+  }
+
+  const cellKey = getCellKey(rowIndex, columnKey)
+  const cells = new Set(selection.cells)
+
+  if (cells.has(cellKey)) {
+    cells.delete(cellKey)
+  } else {
+    cells.add(cellKey)
+  }
+
+  return {
+    ...createEmptySelection('multi-cell'),
+    rowIndex: cells.has(cellKey) ? rowIndex : null,
+    columnKey: cells.has(cellKey) ? columnKey : null,
+    cells
+  }
+}
+
+export { getRowRange }

package/src/features/sorting/sorting.ts

@@ -0,0 +1,46 @@
+import type { GridSortState } from '../../model/GridState.js'
+
+function getRowSortValue(row: unknown, columnKey: string) {
+  if (row && typeof row === 'object' && !Array.isArray(row) && columnKey in row) {
+    return (row as Record<string, unknown>)[columnKey]
+  }
+
+  return row
+}
+
+function normalizeSortValue(value: unknown) {
+  if (value === null || value === undefined) {
+    return ''
+  }
+
+  if (typeof value === 'number') {
+    return value
+  }
+
+  return String(value).toLowerCase()
+}
+
+function compareValues(left: unknown, right: unknown) {
+  const normalizedLeft = normalizeSortValue(left)
+  const normalizedRight = normalizeSortValue(right)
+
+  if (typeof normalizedLeft === 'number' && typeof normalizedRight === 'number') {
+    return normalizedLeft - normalizedRight
+  }
+
+  return String(normalizedLeft).localeCompare(String(normalizedRight))
+}
+
+export function applySortData(data: unknown[], sort: GridSortState) {
+  if (!sort.columnKey || !sort.direction) {
+    return data.slice()
+  }
+
+  return data.slice().sort((a, b) => {
+    const left = getRowSortValue(a, sort.columnKey!)
+    const right = getRowSortValue(b, sort.columnKey!)
+    const comparison = compareValues(left, right)
+
+    return sort.direction === 'asc' ? comparison : -comparison
+  })
+}

package/src/features/transforms/applyDataTransforms.ts

@@ -0,0 +1,13 @@
+import type { GridFilter, GridSortState } from '../../model/GridState.js'
+import { applyFilterData } from '../filtering/filtering.js'
+import { applyQuickSearch } from '../quick-search/quickSearch.js'
+import { applySortData } from '../sorting/sorting.js'
+
+export function applyDataTransforms(
+  data: unknown[],
+  quickSearchQuery: string,
+  filters: GridFilter[],
+  sort: GridSortState
+) {
+  return applySortData(applyFilterData(applyQuickSearch(data, quickSearchQuery), filters), sort)
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export { createGridEngine } from './core/createGridEngine.js'
+export type { GridEngine } from './core/GridEngine.js'
+export type { GridConfig, GridPaginationConfig, ResolvedGridConfig, SelectionMode } from './model/GridConfig.js'
+export type {
+  FilterOperator,
+  GridFilter,
+  GridPaginationState,
+  GridSelection,
+  SelectionIntent,
+  SortDirection
+} from './model/GridState.js'

package/src/model/GridConfig.ts

@@ -0,0 +1,61 @@
+export type SelectionMode = 'none' | 'row' | 'multi-row' | 'cell' | 'multi-cell'
+
+export type GridPaginationConfig = {
+  enabled?: boolean
+  pageSize?: number
+  pageIndex?: number
+}
+
+export type GridConfig = {
+  selection?: {
+    mode?: SelectionMode
+    checkboxes?: boolean
+  }
+  rowHeader?: {
+    enabled?: boolean
+    width?: number
+  }
+  pagination?: GridPaginationConfig
+}
+
+export type ResolvedGridConfig = {
+  selection: {
+    mode: SelectionMode
+    checkboxes: boolean
+  }
+  rowHeader: {
+    enabled: boolean
+    width: number
+  }
+  pagination: {
+    enabled: boolean
+    pageSize: number
+    pageIndex: number
+  }
+}
+
+function normalizePageSize(value: number | undefined) {
+  return Number.isFinite(value) && value! > 0 ? Math.max(1, Math.floor(value!)) : 50
+}
+
+function normalizePageIndex(value: number | undefined) {
+  return Number.isFinite(value) && value! >= 0 ? Math.floor(value!) : 0
+}
+
+export function normalizeConfig(config: GridConfig = {}): ResolvedGridConfig {
+  return {
+    selection: {
+      mode: config.selection?.mode ?? 'none',
+      checkboxes: config.selection?.checkboxes ?? false
+    },
+    rowHeader: {
+      enabled: config.rowHeader?.enabled ?? false,
+      width: config.rowHeader?.width ?? 56
+    },
+    pagination: {
+      enabled: config.pagination?.enabled ?? false,
+      pageSize: normalizePageSize(config.pagination?.pageSize),
+      pageIndex: normalizePageIndex(config.pagination?.pageIndex)
+    }
+  }
+}

package/src/model/GridState.ts

@@ -0,0 +1,57 @@
+import type { ResolvedGridConfig, SelectionMode } from './GridConfig.js'
+
+export type SelectionIntent = 'replace' | 'toggle' | 'range'
+
+export type GridSelection = {
+  mode: SelectionMode
+  rowIndex: number | null
+  columnKey: string | null
+  anchorRowIndex: number | null
+  rowIndexes: Set<number>
+  cells: Set<string>
+}
+
+export type SortDirection = 'asc' | 'desc'
+
+export type GridSortState = {
+  columnKey: string | null
+  direction: SortDirection | null
+}
+
+export type FilterOperator =
+  | 'contains'
+  | 'equals'
+  | 'startsWith'
+  | 'endsWith'
+  | 'isEmpty'
+  | 'isNotEmpty'
+  | 'greaterThan'
+  | 'greaterThanOrEqual'
+  | 'lessThan'
+  | 'lessThanOrEqual'
+
+export type GridFilter = {
+  columnKey: string
+  operator: FilterOperator
+  value?: unknown
+}
+
+export type GridPaginationState = {
+  enabled: boolean
+  pageIndex: number
+  pageSize: number
+  totalRows: number
+  pageCount: number
+}
+
+export type GridState = {
+  config: ResolvedGridConfig
+  originalData: unknown[]
+  transformedData: unknown[]
+  data: unknown[]
+  sort: GridSortState
+  quickSearchQuery: string
+  filters: GridFilter[]
+  pagination: GridPaginationState
+  selection: GridSelection
+}

package/src/utils/range.ts

@@ -0,0 +1,11 @@
+export function getRowRange(startIndex: number, endIndex: number) {
+  const firstIndex = Math.min(startIndex, endIndex)
+  const lastIndex = Math.max(startIndex, endIndex)
+  const rowIndexes = new Set<number>()
+
+  for (let index = firstIndex; index <= lastIndex; index += 1) {
+    rowIndexes.add(index)
+  }
+
+  return rowIndexes
+}