@purestack/ts-components 1.1.0

package/src/standard/virtualList/virtualList.ts

@@ -0,0 +1,423 @@
+import {
+  type ComponentHead,
+  type ComputedRef,
+  computed,
+  defineComponent,
+  html,
+  observe,
+  type RefOrValue,
+  ref,
+  sref,
+  unref,
+} from 'regor'
+
+export interface VirtualListRow {
+  index: number
+  item: unknown
+}
+
+export interface VirtualList {
+  items?: RefOrValue<unknown[]>
+  height?: RefOrValue<number | string>
+  itemHeight?: RefOrValue<number | string>
+  overscan?: RefOrValue<number | string>
+  rowComponent?: RefOrValue<string>
+  scrollTop?: ReturnType<typeof ref<number>>
+  visibleRows?: ComputedRef<VirtualListRow[]>
+  viewportStyle?: ComputedRef<Record<string, string>>
+  spacerStyle?: ComputedRef<Record<string, string>>
+  windowStyle?: ComputedRef<Record<string, string>>
+  itemStyle?: ComputedRef<Record<string, string>>
+  handleScroll?: (event: Event) => void
+  resolvedRowComponent?: ComputedRef<string>
+}
+
+export interface VariableVirtualList extends VirtualList {
+  estimateHeight?: RefOrValue<number | string>
+  rowElementRefs?: Array<ReturnType<typeof sref<HTMLElement | null>>>
+  viewportElement?: ReturnType<typeof sref<HTMLElement | null>>
+  unmounted?: () => void
+}
+
+const virtualListTemplate = html`<div class="virtual-list" :style="viewportStyle" @scroll="handleScroll">
+  <div class="virtual-list__spacer" :style="spacerStyle">
+    <div class="virtual-list__window" :style="windowStyle">
+      <div
+        class="virtual-list__item"
+        :style="itemStyle"
+        r-for="row in visibleRows"
+      >
+        <div
+          :is="resolvedRowComponent"
+          :item="row.item"
+          :index="row.index"
+        ></div>
+      </div>
+    </div>
+  </div>
+</div>`
+
+function defineVirtualListComponent() {
+  return defineComponent<VirtualList>(virtualListTemplate, {
+    props: ['items', 'height', 'itemHeight', 'overscan', 'rowComponent'],
+    context: (head) => resolveVirtualList(head),
+  })
+}
+
+const variableVirtualListTemplate = html`<div
+  class="virtual-list variable-virtual-list"
+  :style="viewportStyle"
+  :ref="viewportElement"
+  @scroll="handleScroll"
+>
+  <div class="virtual-list__spacer" :style="spacerStyle">
+    <div class="virtual-list__window" :style="windowStyle">
+      <div
+        class="virtual-list__item"
+        :ref="rowElementRefs[row.index]"
+        r-for="row in visibleRows"
+      >
+        <div
+          :is="resolvedRowComponent"
+          :item="row.item"
+          :index="row.index"
+        ></div>
+      </div>
+    </div>
+  </div>
+</div>`
+
+function defineVariableVirtualListComponent() {
+  return defineComponent<VariableVirtualList>(variableVirtualListTemplate, {
+    props: ['items', 'height', 'estimateHeight', 'overscan', 'rowComponent'],
+    context: (head) => resolveVariableVirtualList(head),
+  })
+}
+
+export function defineVirtualListComponents() {
+  return {
+    virtualList: defineVirtualListComponent(),
+    variableVirtualList: defineVariableVirtualListComponent(),
+  }
+}
+
+function resolveVirtualList(head: ComponentHead<VirtualList>) {
+  const props = head.props
+  const scrollTop = ref(0)
+  const itemHeight = computed(() => resolvePositiveNumber(props.itemHeight, 44))
+  const height = computed(() => resolvePositiveNumber(props.height, 560))
+  const overscan = computed(() =>
+    Math.trunc(resolvePositiveNumber(props.overscan, 6)),
+  )
+  const items = computed(() => {
+    const value = unref(props.items)
+    return Array.isArray(value) ? value : []
+  })
+  const startIndex = computed(() =>
+    Math.max(0, Math.floor(scrollTop() / itemHeight()) - overscan()),
+  )
+  const visibleCount = computed(
+    () => Math.ceil(height() / itemHeight()) + overscan() * 2,
+  )
+  const visibleRows = computed(() => {
+    const source = items()
+    const start = startIndex()
+    const end = Math.min(source.length, start + visibleCount())
+    const rows: VirtualListRow[] = []
+    for (let index = start; index < end; index += 1)
+      rows.push({ index, item: source[index] })
+
+    return rows
+  })
+
+  return {
+    ...props,
+    scrollTop,
+    visibleRows,
+    viewportStyle: computed<Record<string, string>>(() => ({
+      height: `${height()}px`,
+    })),
+    spacerStyle: computed<Record<string, string>>(() => ({
+      height: `${items().length * itemHeight()}px`,
+    })),
+    windowStyle: computed<Record<string, string>>(() => ({
+      transform: `translateY(${startIndex() * itemHeight()}px)`,
+    })),
+    itemStyle: computed<Record<string, string>>(() => ({
+      height: `${itemHeight()}px`,
+    })),
+    resolvedRowComponent: computed(() => {
+      const component = unref(props.rowComponent)
+      return typeof component === 'string' && component.trim()
+        ? component
+        : 'div'
+    }),
+    handleScroll: (event: Event) => {
+      const target = event.currentTarget
+      if (target instanceof HTMLElement) scrollTop(target.scrollTop)
+    },
+  }
+}
+
+function resolvePositiveNumber(
+  value: RefOrValue<number | string> | undefined,
+  fallback: number,
+) {
+  const raw = unref(value)
+  const parsed = typeof raw === 'number' ? raw : Number.parseFloat(String(raw))
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback
+}
+
+class VariableVirtualListContext {
+  readonly scrollTop = ref(0)
+  readonly viewportElement = sref<HTMLElement | null>(null)
+  readonly rowElementRefs: Array<ReturnType<typeof sref<HTMLElement | null>>> =
+    []
+  readonly visibleRows: ComputedRef<VirtualListRow[]>
+  readonly viewportStyle: ComputedRef<Record<string, string>>
+  readonly spacerStyle: ComputedRef<Record<string, string>>
+  readonly windowStyle: ComputedRef<Record<string, string>>
+  readonly resolvedRowComponent: ComputedRef<string>
+  private readonly rowHeights: number[] = []
+  private rowWindow = new Map<number, VirtualListRow>()
+  private readonly rowObservers = new Map<number, ResizeObserver>()
+  private readonly measurementVersion = ref(0)
+  private measuredHeightTotal = 0
+  private measuredRowCount = 0
+  private readonly resolvedItems: ComputedRef<unknown[]>
+  private readonly resolvedHeight: ComputedRef<number>
+  private readonly resolvedEstimateHeight: ComputedRef<number>
+  private readonly resolvedOverscan: ComputedRef<number>
+  private readonly offsets: ComputedRef<number[]>
+  private readonly startIndex: ComputedRef<number>
+  private readonly firstVisibleIndex: ComputedRef<number>
+  private readonly normalizedScrollTop: ComputedRef<number>
+  private pendingIndexes = new Set<number>()
+  private pendingFrame = 0
+  private scrollEndTimer: ReturnType<typeof setTimeout> | undefined
+  private isScrolling = false
+  private hasDeferredMeasurements = false
+
+  constructor(props: VariableVirtualList) {
+    this.resolvedItems = computed(() => {
+      const value = unref(props.items)
+      return Array.isArray(value) ? value : []
+    })
+    this.resolvedHeight = computed(() =>
+      resolvePositiveNumber(props.height, 560),
+    )
+    this.resolvedEstimateHeight = computed(() =>
+      resolvePositiveNumber(props.estimateHeight ?? props.itemHeight, 56),
+    )
+    this.resolvedOverscan = computed(() =>
+      Math.trunc(resolvePositiveNumber(props.overscan, 6)),
+    )
+    this.offsets = computed(() => {
+      this.measurementVersion()
+      const estimate = this.currentEstimateHeight()
+      const source = this.resolvedItems()
+      const offsets = new Array<number>(source.length + 1)
+      offsets[0] = 0
+      for (let index = 0; index < source.length; index += 1)
+        offsets[index + 1] =
+          (offsets[index] ?? 0) + (this.rowHeights[index] ?? estimate)
+
+      return offsets
+    })
+    this.normalizedScrollTop = computed(() => {
+      const value = this.scrollTop()
+      return value <= 0.5 ? 0 : value
+    })
+    this.firstVisibleIndex = computed(() =>
+      findOffsetIndex(this.offsets(), this.normalizedScrollTop()),
+    )
+    this.startIndex = computed(() =>
+      Math.max(0, this.firstVisibleIndex() - this.resolvedOverscan()),
+    )
+    this.visibleRows = computed(() => this.resolveVisibleRows())
+    this.viewportStyle = computed<Record<string, string>>(() => ({
+      height: `${this.resolvedHeight()}px`,
+    }))
+    this.spacerStyle = computed<Record<string, string>>(() => {
+      const offsets = this.offsets()
+      return {
+        height: `${offsets[offsets.length - 1] ?? 0}px`,
+      }
+    })
+    this.windowStyle = computed<Record<string, string>>(() => ({
+      transform: `translateY(${this.offsets()[this.startIndex()] ?? 0}px)`,
+    }))
+    this.resolvedRowComponent = computed(() => {
+      const component = unref(props.rowComponent)
+      return typeof component === 'string' && component.trim()
+        ? component
+        : 'div'
+    })
+  }
+
+  handleScroll = () => {
+    this.syncScrollTopFromViewport()
+
+    this.isScrolling = true
+    if (this.scrollEndTimer !== undefined) clearTimeout(this.scrollEndTimer)
+    this.scrollEndTimer = setTimeout(() => {
+      this.scrollEndTimer = undefined
+      this.isScrolling = false
+      this.syncScrollTopFromViewport()
+      if (!this.hasDeferredMeasurements) return
+
+      this.hasDeferredMeasurements = false
+      this.measurementVersion(this.measurementVersion() + 1)
+    }, 120)
+  }
+
+  unmounted = () => {
+    if (this.pendingFrame) cancelAnimationFrame(this.pendingFrame)
+    if (this.scrollEndTimer !== undefined) clearTimeout(this.scrollEndTimer)
+    for (const observer of this.rowObservers.values()) observer.disconnect()
+    this.rowObservers.clear()
+  }
+
+  private resolveVisibleRows() {
+    const source = this.resolvedItems()
+    const offsets = this.offsets()
+    const scrollTop = this.normalizedScrollTop()
+    const overscan = this.resolvedOverscan()
+    // Resolve both boundaries from the same scroll position. A separate
+    // computed start can still hold its previous value during notification.
+    const start = Math.max(0, findOffsetIndex(offsets, scrollTop) - overscan)
+    const viewportBottom = scrollTop + this.resolvedHeight()
+    let end = findOffsetIndex(offsets, viewportBottom) + overscan + 1
+    end = Math.min(source.length, Math.max(start, end))
+
+    const rows: VirtualListRow[] = []
+    const nextWindow = new Map<number, VirtualListRow>()
+    for (let index = start; index < end; index += 1) {
+      this.ensureRowRef(index)
+      const previous = this.rowWindow.get(index)
+      const row =
+        previous && previous.item === source[index]
+          ? previous
+          : { index, item: source[index] }
+      rows.push(row)
+      nextWindow.set(index, row)
+    }
+    this.rowWindow = nextWindow
+
+    return rows
+  }
+
+  private ensureRowRef(index: number) {
+    if (this.rowElementRefs[index]) return
+
+    const elementRef = sref<HTMLElement | null>(null)
+    this.rowElementRefs[index] = elementRef
+    observe(elementRef, (element) => {
+      this.observeRowElement(index, element)
+    })
+  }
+
+  private observeRowElement(index: number, element: HTMLElement | null) {
+    const existing = this.rowObservers.get(index)
+    if (existing) {
+      existing.disconnect()
+      this.rowObservers.delete(index)
+    }
+    if (!element) return
+
+    const observer = new ResizeObserver(() => {
+      this.queueMeasurement(index)
+    })
+    observer.observe(element)
+    this.rowObservers.set(index, observer)
+    this.queueMeasurement(index)
+  }
+
+  private queueMeasurement(index: number) {
+    this.pendingIndexes.add(index)
+    if (this.pendingFrame) return
+
+    this.pendingFrame = requestAnimationFrame(() => {
+      this.pendingFrame = 0
+      this.flushMeasurements()
+    })
+  }
+
+  private flushMeasurements() {
+    this.syncScrollTopFromViewport()
+    let changed = false
+
+    for (const index of this.pendingIndexes) {
+      const element = this.rowElementRefs[index]?.()
+      if (!element) continue
+
+      const previous = this.rowHeights[index] ?? this.currentEstimateHeight()
+      const next = element.getBoundingClientRect().height
+      if (!Number.isFinite(next) || next <= 0) continue
+      if (Math.abs(previous - next) < 0.5) continue
+
+      this.updateMeasuredAverage(index, next)
+      this.rowHeights[index] = next
+      changed = true
+    }
+
+    this.pendingIndexes.clear()
+    if (!changed) return
+
+    if (this.isScrolling) {
+      this.hasDeferredMeasurements = true
+      return
+    }
+
+    this.measurementVersion(this.measurementVersion() + 1)
+  }
+
+  private currentEstimateHeight() {
+    if (this.measuredRowCount === 0) return this.resolvedEstimateHeight()
+    return this.measuredHeightTotal / this.measuredRowCount
+  }
+
+  private updateMeasuredAverage(index: number, next: number) {
+    const previous = this.rowHeights[index]
+    if (previous === undefined) {
+      this.measuredRowCount += 1
+      this.measuredHeightTotal += next
+      return
+    }
+
+    this.measuredHeightTotal += next - previous
+  }
+
+  private syncScrollTopFromViewport() {
+    const viewport = this.viewportElement()
+    if (!viewport) return
+
+    this.setScrollTop(viewport.scrollTop)
+  }
+
+  private setScrollTop(value: number) {
+    const next = Number.isFinite(value) && value > 0 ? value : 0
+    if (this.scrollTop() === next) return
+
+    this.scrollTop(next)
+  }
+}
+
+function resolveVariableVirtualList(head: ComponentHead<VariableVirtualList>) {
+  head.autoProps = false
+  return new VariableVirtualListContext(head.props) as VariableVirtualList
+}
+
+function findOffsetIndex(offsets: number[], scrollTop: number) {
+  if (offsets.length <= 1) return 0
+
+  let low = 0
+  let high = offsets.length - 1
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2)
+    if ((offsets[middle] ?? 0) <= scrollTop) low = middle + 1
+    else high = middle
+  }
+
+  return Math.max(0, low - 1)
+}

package/src/standard/virtualList/virtualListStyle.ts

@@ -0,0 +1,34 @@
+import { styleBuilder, themes } from '@purestack/ts-style'
+
+export function registerVirtualListStyles() {
+  themes.forEach((theme) => {
+    styleBuilder
+      .select('.virtual-list', theme)
+      .overflowY('auto')
+      .overflowX('auto')
+      .minWidth('0')
+
+    styleBuilder
+      .select('.virtual-list__spacer', theme)
+      .position('relative')
+      .minWidth('0')
+
+    styleBuilder
+      .select('.virtual-list__window', theme)
+      .position('absolute')
+      .top('0')
+      .right('0')
+      .left('0')
+      .willChange('transform')
+
+    styleBuilder
+      .select('.virtual-list__item', theme)
+      .overflow('visible')
+      .minWidth('0')
+
+    styleBuilder
+      .select('.variable-virtual-list .virtual-list__item', theme)
+      .overflow('visible')
+      .minWidth('0')
+  })
+}

package/src/standard/virtualList/virtualTable.ts

@@ -0,0 +1,179 @@
+import {
+  type ComponentHead,
+  type ComputedRef,
+  computed,
+  defineComponent,
+  html,
+  type RefOrValue,
+  ref,
+  unref,
+} from 'regor'
+import type { VirtualListRow } from './virtualList'
+
+export interface VirtualTable {
+  items?: RefOrValue<unknown[]>
+  height?: RefOrValue<number | string>
+  itemHeight?: RefOrValue<number | string>
+  overscan?: RefOrValue<number | string>
+  rowComponent?: RefOrValue<string>
+  colGroupComponent?: RefOrValue<string>
+  headerComponent?: RefOrValue<string>
+  footerComponent?: RefOrValue<string>
+  tableLayout?: RefOrValue<'auto' | 'fixed'>
+  scrollTop?: ReturnType<typeof ref<number>>
+  visibleRows?: ComputedRef<VirtualListRow[]>
+  viewportStyle?: ComputedRef<Record<string, string>>
+  tableStyle?: ComputedRef<Record<string, string>>
+  topSpacerStyle?: ComputedRef<Record<string, string>>
+  bottomSpacerStyle?: ComputedRef<Record<string, string>>
+  handleScroll?: (event: Event) => void
+  hasColGroupComponent?: ComputedRef<boolean>
+  hasHeaderComponent?: ComputedRef<boolean>
+  hasFooterComponent?: ComputedRef<boolean>
+}
+
+const virtualTableTemplate = html`<div class="virtual-table" :style="viewportStyle" @scroll="handleScroll">
+  <table class="virtual-table__table" :style="tableStyle">
+    <colgroup :is="colGroupComponent" r-if="hasColGroupComponent"></colgroup>
+    <thead :is="headerComponent" r-if="hasHeaderComponent"></thead>
+    <tbody>
+      <tr class="virtual-table__spacer-row">
+        <td :style="topSpacerStyle"></td>
+      </tr>
+      <tr
+        :is="rowComponent"
+        :item="row.item"
+        :index="row.index"
+        style="height: var(--virtual-table-item-height) !important;"
+        r-for="row in visibleRows"
+      ></tr>
+      <tr class="virtual-table__spacer-row">
+        <td :style="bottomSpacerStyle"></td>
+      </tr>
+    </tbody>
+    <tfoot :is="footerComponent" r-if="hasFooterComponent"></tfoot>
+  </table>
+</div>`
+
+function defineVirtualTableComponent() {
+  return defineComponent<VirtualTable>(virtualTableTemplate, {
+    props: [
+      'items',
+      'height',
+      'itemHeight',
+      'overscan',
+      'rowComponent',
+      'colGroupComponent',
+      'headerComponent',
+      'footerComponent',
+      'tableLayout',
+    ],
+    context: (head) => resolveVirtualTable(head),
+  })
+}
+
+export function defineVirtualTableComponents() {
+  return {
+    virtualTable: defineVirtualTableComponent(),
+  }
+}
+
+function resolveVirtualTable(head: ComponentHead<VirtualTable>) {
+  const props = head.props
+  const window = resolveFixedVirtualWindow(props)
+  const endIndex = computed(() => {
+    const rows = window.visibleRows()
+    const last = rows[rows.length - 1]
+    return last ? last.index + 1 : window.startIndex()
+  })
+
+  return {
+    ...props,
+    scrollTop: window.scrollTop,
+    visibleRows: window.visibleRows,
+    viewportStyle: computed<Record<string, string>>(() => ({
+      height: `${window.height()}px`,
+      overflow: 'auto',
+      width: '100%',
+      maxWidth: '100%',
+      boxSizing: 'border-box',
+      minWidth: '0',
+    })),
+    tableStyle: computed<Record<string, string>>(() => {
+      const fixed = unref(props.tableLayout) === 'fixed'
+      return {
+        '--virtual-table-item-height': `${window.itemHeight()}px`,
+        width: fixed ? '100%' : 'max-content',
+        minWidth: '100%',
+        borderCollapse: 'separate',
+        borderSpacing: '0',
+        tableLayout: fixed ? 'fixed' : 'auto',
+      }
+    }),
+    topSpacerStyle: computed<Record<string, string>>(() => ({
+      height: `${window.startIndex() * window.itemHeight()}px`,
+      padding: '0',
+      border: '0',
+    })),
+    bottomSpacerStyle: computed<Record<string, string>>(() => ({
+      height: `${Math.max(0, window.items().length - endIndex()) * window.itemHeight()}px`,
+      padding: '0',
+      border: '0',
+    })),
+    hasColGroupComponent: computed(() => !!unref(props.colGroupComponent)),
+    hasHeaderComponent: computed(() => !!unref(props.headerComponent)),
+    hasFooterComponent: computed(() => !!unref(props.footerComponent)),
+    handleScroll: window.handleScroll,
+  }
+}
+
+function resolveFixedVirtualWindow(props: VirtualTable) {
+  const scrollTop = ref(0)
+  const itemHeight = computed(() => resolvePositiveNumber(props.itemHeight, 44))
+  const height = computed(() => resolvePositiveNumber(props.height, 560))
+  const overscan = computed(() =>
+    Math.trunc(resolvePositiveNumber(props.overscan, 6)),
+  )
+  const items = computed(() => {
+    const value = unref(props.items)
+    return Array.isArray(value) ? value : []
+  })
+  const startIndex = computed(() =>
+    Math.max(0, Math.floor(scrollTop() / itemHeight()) - overscan()),
+  )
+  const visibleCount = computed(
+    () => Math.ceil(height() / itemHeight()) + overscan() * 2,
+  )
+  const visibleRows = computed(() => {
+    const source = items()
+    const start = startIndex()
+    const end = Math.min(source.length, start + visibleCount())
+    const rows: VirtualListRow[] = []
+    for (let index = start; index < end; index += 1)
+      rows.push({ index, item: source[index] })
+
+    return rows
+  })
+
+  return {
+    scrollTop,
+    itemHeight,
+    height,
+    items,
+    startIndex,
+    visibleRows,
+    handleScroll: (event: Event) => {
+      const target = event.currentTarget
+      if (target instanceof HTMLElement) scrollTop(target.scrollTop)
+    },
+  }
+}
+
+function resolvePositiveNumber(
+  value: RefOrValue<number | string> | undefined,
+  fallback: number,
+) {
+  const raw = unref(value)
+  const parsed = typeof raw === 'number' ? raw : Number.parseFloat(String(raw))
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback
+}

package/src/standard/virtualList/virtualTableStyle.ts

@@ -0,0 +1,24 @@
+import { styleBuilder, themes } from '@purestack/ts-style'
+
+export function registerVirtualTableStyles() {
+  themes.forEach((theme) => {
+    styleBuilder
+      .select('.virtual-table__table th, .virtual-table__table td', theme)
+      .verticalAlign('middle')
+
+    styleBuilder
+      .select('.virtual-table__table thead', theme)
+      .position('sticky')
+      .top('0')
+      .zIndex(2)
+
+    styleBuilder
+      .select(
+        '.virtual-table__table tfoot th, .virtual-table__table tfoot td',
+        theme,
+      )
+      .position('sticky')
+      .bottom('0')
+      .zIndex(1)
+  })
+}

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "noImplicitOverride": true,
+    "noImplicitAny": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "types": [],
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "paths": {
+      "@purestack/*": ["../../packages/*/src"]
+    }
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/test/**", "src/**/*.test.ts", "src/**/*.spec.ts"]
+}