@tipolox/litgrid-renderer 1.0.3 → 1.1.0

package/README.md

@@ -16,6 +16,7 @@ npm install @tipolox/litgrid-renderer
 - [Renderer utilities API](https://github.com/tipolox/litgrid/blob/main/docs/api-reference.md#renderer-utilities)
 - [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-renderer",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Virtualization and scroll-mapping utilities 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/index.ts

@@ -0,0 +1,20 @@
+export { createVirtualizer } from './virtualization/createVirtualizer.js'
+export { createVariableVirtualizer } from './virtualization/createVariableVirtualizer.js'
+export { calculateDisplayLayout, mapDisplayScrollOffset } from './viewport/scrollMapping.js'
+export type {
+  FixedVirtualizer,
+  FixedVirtualRange,
+  VariableVirtualizerOptions,
+  VariableVirtualizerState,
+  VariableVirtualizer,
+  VariableVirtualRange,
+  VirtualRange,
+  VirtualizerOptions,
+  VirtualizerState
+} from './virtualization/types.js'
+export type {
+  DisplayLayout,
+  DisplayLayoutOptions,
+  ScrollMappingOptions,
+  ScrollMappingResult
+} from './viewport/scrollMapping.js'

package/src/utils/math.ts

@@ -0,0 +1,13 @@
+export function clamp(value: number, min: number, max: number) {
+  return Math.min(Math.max(value, min), max)
+}
+
+export function sumSizes(sizes: number[], startIndex: number, endIndex: number) {
+  let total = 0
+
+  for (let index = startIndex; index < endIndex; index += 1) {
+    total += Math.max(1, sizes[index] ?? 0)
+  }
+
+  return total
+}

package/src/viewport/scrollMapping.ts

@@ -0,0 +1,83 @@
+import { clamp } from '../utils/math.js'
+
+export type ScrollMappingOptions = {
+  displayScrollOffset: number
+  previousDisplayScrollOffset: number
+  displaySize: number
+  totalSize: number
+  viewportSize: number
+}
+
+export type ScrollMappingResult = {
+  availableDisplaySize: number
+  availableVirtualSize: number
+  scrollOffset: number
+}
+
+export function mapDisplayScrollOffset({
+  displayScrollOffset,
+  previousDisplayScrollOffset,
+  displaySize,
+  totalSize,
+  viewportSize
+}: ScrollMappingOptions): ScrollMappingResult {
+  const availableDisplaySize = Math.max(0, displaySize - viewportSize)
+  const availableVirtualSize = Math.max(0, totalSize - viewportSize)
+
+  if (totalSize > 0 && availableDisplaySize > 0 && availableVirtualSize > 0) {
+    const ratio = displayScrollOffset / availableDisplaySize
+    const desiredScrollOffset = ratio * availableVirtualSize
+    let scrollOffset = clamp(
+      Number.isFinite(desiredScrollOffset) ? desiredScrollOffset : 0,
+      0,
+      availableVirtualSize
+    )
+
+    const bottomThreshold = 1
+    const isScrollingDown = displayScrollOffset >= previousDisplayScrollOffset
+    if (isScrollingDown && displayScrollOffset >= Math.max(0, availableDisplaySize - bottomThreshold)) {
+      scrollOffset = availableVirtualSize
+    }
+
+    return { availableDisplaySize, availableVirtualSize, scrollOffset }
+  }
+
+  return {
+    availableDisplaySize,
+    availableVirtualSize,
+    scrollOffset: clamp(displayScrollOffset, 0, availableVirtualSize)
+  }
+}
+
+export type DisplayLayoutOptions = {
+  totalSize: number
+  displaySize: number
+  virtualOffsetTop: number
+  visibleSize: number
+  bottomPadding: number
+}
+
+export type DisplayLayout = {
+  displayScale: number
+  displayOffsetTop: number
+  displayBottomPadding: number
+}
+
+export function calculateDisplayLayout({
+  totalSize,
+  displaySize,
+  virtualOffsetTop,
+  visibleSize,
+  bottomPadding
+}: DisplayLayoutOptions): DisplayLayout {
+  const displayScale = totalSize > 0 ? displaySize / totalSize : 1
+
+  return {
+    displayScale,
+    displayOffsetTop: Math.min(
+      virtualOffsetTop * displayScale,
+      Math.max(0, displaySize - visibleSize)
+    ),
+    displayBottomPadding: bottomPadding * displayScale
+  }
+}

package/src/virtualization/createVariableVirtualizer.ts

@@ -0,0 +1,78 @@
+import { clamp, sumSizes } from '../utils/math.js'
+import type {
+  VariableVirtualizer,
+  VariableVirtualizerOptions,
+  VariableVirtualizerState
+} from './types.js'
+
+export function createVariableVirtualizer({
+  sizes,
+  viewportSize,
+  overscan = 2
+}: VariableVirtualizerOptions): VariableVirtualizer {
+  let state: VariableVirtualizerState = {
+    sizes,
+    viewportSize,
+    overscan,
+    scrollOffset: 0
+  }
+
+  return {
+    setOptions(next: Partial<VariableVirtualizerState>) {
+      state = {
+        ...state,
+        ...next
+      }
+    },
+    setScrollOffset(scrollOffset: number) {
+      state.scrollOffset = scrollOffset
+    },
+    getState() {
+      const sizes = state.sizes.map((size) => Math.max(1, size))
+      const count = sizes.length
+      const totalSize = sumSizes(sizes, 0, count)
+      const safeViewportSize = Math.max(0, state.viewportSize)
+      const safeOverscan = Math.max(0, state.overscan)
+      const safeScrollOffset = clamp(state.scrollOffset, 0, totalSize)
+
+      let baseStartIndex = 0
+      let baseStartOffset = 0
+
+      while (
+        baseStartIndex < count &&
+        baseStartOffset + sizes[baseStartIndex] <= safeScrollOffset
+      ) {
+        baseStartOffset += sizes[baseStartIndex]
+        baseStartIndex += 1
+      }
+
+      let visibleEndIndex = baseStartIndex
+      let visibleEndOffset = baseStartOffset
+
+      while (
+        visibleEndIndex < count &&
+        visibleEndOffset < safeScrollOffset + safeViewportSize
+      ) {
+        visibleEndOffset += sizes[visibleEndIndex]
+        visibleEndIndex += 1
+      }
+
+      const startIndex = clamp(baseStartIndex - safeOverscan, 0, count)
+      const endIndex = clamp(visibleEndIndex + safeOverscan, startIndex, count)
+      const leftPadding = sumSizes(sizes, 0, startIndex)
+      const visibleSize = sumSizes(sizes, startIndex, endIndex)
+      const rightPadding = Math.max(0, totalSize - leftPadding - visibleSize)
+
+      return {
+        startIndex,
+        endIndex,
+        leftPadding,
+        rightPadding,
+        offsetTop: leftPadding,
+        bottomPadding: rightPadding,
+        totalSize,
+        visibleSize
+      }
+    }
+  }
+}

package/src/virtualization/createVirtualizer.ts

@@ -0,0 +1,65 @@
+import { clamp } from '../utils/math.js'
+import type { FixedVirtualizer, VirtualizerOptions, VirtualizerState } from './types.js'
+
+export function createVirtualizer({
+  rowHeight,
+  viewportHeight,
+  overscan = 4
+}: VirtualizerOptions): FixedVirtualizer {
+  let state: VirtualizerState = {
+    rowHeight,
+    viewportHeight,
+    overscan,
+    scrollTop: 0
+  }
+
+  return {
+    setOptions(next: Partial<VirtualizerState>) {
+      state = {
+        ...state,
+        ...next
+      }
+    },
+    setScrollTop(scrollTop: number) {
+      state.scrollTop = scrollTop
+    },
+    setScrollOffset(scrollTop: number) {
+      state.scrollTop = scrollTop
+    },
+    getState(count: number) {
+      const safeCount = Math.max(0, count)
+      const safeRowHeight = Math.max(1, state.rowHeight)
+      const safeViewportHeight = Math.max(0, state.viewportHeight)
+      const safeOverscan = Math.max(0, state.overscan)
+      const visibleCount = Math.max(1, Math.ceil(safeViewportHeight / safeRowHeight))
+      const maxStartIndex = Math.max(0, safeCount - visibleCount)
+
+      const baseStartIndex = clamp(
+        Math.floor(state.scrollTop / safeRowHeight),
+        0,
+        maxStartIndex
+      )
+
+      const startIndex = clamp(baseStartIndex - safeOverscan, 0, safeCount)
+      const endIndex = clamp(
+        baseStartIndex + visibleCount + safeOverscan,
+        startIndex,
+        safeCount
+      )
+      const offsetTop = startIndex * safeRowHeight
+      const totalHeight = safeCount * safeRowHeight
+      const visibleSize = (endIndex - startIndex) * safeRowHeight
+
+      return {
+        startIndex,
+        endIndex,
+        offsetTop,
+        bottomPadding: Math.max(0, totalHeight - endIndex * safeRowHeight),
+        totalHeight,
+        totalSize: totalHeight,
+        visibleCount,
+        visibleSize
+      }
+    }
+  }
+}

package/src/virtualization/types.ts

@@ -0,0 +1,57 @@
+export type VirtualizerOptions = {
+  rowHeight: number
+  viewportHeight: number
+  overscan?: number
+}
+
+export type VirtualizerState = {
+  rowHeight: number
+  viewportHeight: number
+  overscan: number
+  scrollTop: number
+}
+
+export type VirtualRange = {
+  startIndex: number
+  endIndex: number
+  offsetTop: number
+  bottomPadding: number
+  totalSize: number
+  visibleSize: number
+}
+
+export type FixedVirtualRange = VirtualRange & {
+  totalHeight: number
+  visibleCount: number
+}
+
+export type FixedVirtualizer = {
+  setOptions: (next: Partial<VirtualizerState>) => void
+  setScrollTop: (scrollTop: number) => void
+  setScrollOffset: (scrollTop: number) => void
+  getState: (count: number) => FixedVirtualRange
+}
+
+export type VariableVirtualizerOptions = {
+  sizes: number[]
+  viewportSize: number
+  overscan?: number
+}
+
+export type VariableVirtualizerState = {
+  sizes: number[]
+  viewportSize: number
+  overscan: number
+  scrollOffset: number
+}
+
+export type VariableVirtualRange = VirtualRange & {
+  leftPadding: number
+  rightPadding: number
+}
+
+export type VariableVirtualizer = {
+  setOptions: (next: Partial<VariableVirtualizerState>) => void
+  setScrollOffset: (scrollOffset: number) => void
+  getState: () => VariableVirtualRange
+}