@pgcorp/ui-kit 0.8.1 → 0.9.0

package/src/components/shared/data-display/SVirtualList.vue

@@ -6,10 +6,17 @@
     :style="containerStyle"
     :data-item-size="itemSize"
     :data-viewport-height="height ?? undefined"
-    role="list"
+    :role="validatedSemanticRole"
     :aria-label="accessibleLabel"
+    :aria-live="validatedSemanticRole === 'log' ? validatedLive : undefined"
+    :aria-busy="validatedSemanticRole === 'log' ? validatedBusy : undefined"
+    :aria-relevant="validatedSemanticRole === 'log' ? 'additions text' : undefined"
     tabindex="0"
     @scroll.passive="updateViewport"
+    @wheel.passive="handleWheel"
+    @keydown="handleKeydown"
+    @pointerdown="handlePointerDown"
+    @pointerup="handlePointerUp"
   >
     <div class="s-virtual-list__spacer" :style="spacerStyle" aria-hidden="true" />
     <div
@@ -19,7 +26,7 @@
       class="s-virtual-list__item"
       :style="itemStyle(entry.index)"
       :data-virtual-index="entry.index"
-      role="listitem"
+      :role="validatedSemanticRole === 'list' ? 'listitem' : 'article'"
       :aria-label="resolveItemLabel(entry.item, entry.index)"
       :aria-posinset="entry.index + 1"
       :aria-setsize="items.length"
@@ -36,7 +43,12 @@
 </template>
 
 <script lang="ts">
-import type { SVirtualListItemKey } from './SVirtualList'
+import type {
+  SVirtualListItemKey,
+  SVirtualListLiveMode,
+  SVirtualListSemanticRole,
+  SVirtualListViewportState,
+} from './SVirtualList'
 
 /** Публичный контракт virtual list принадлежит source-SFC runtime. / The public virtual-list contract is owned by the source-SFC runtime. */
 export interface SVirtualListProps<Item = unknown> {
@@ -50,6 +62,13 @@ export interface SVirtualListProps<Item = unknown> {
   itemLabel: (item: Item, index: number) => string
   accessibleLabel: string
   externalScrollTarget?: HTMLElement | null
+  /** Controlled follow-tail intent. Use v-model:followTail when user detachment must persist in the parent. */
+  followTail?: boolean
+  nearStartThreshold?: number
+  endThreshold?: number
+  semanticRole?: SVirtualListSemanticRole
+  live?: SVirtualListLiveMode
+  busy?: boolean
 }
 </script>
 
@@ -65,17 +84,40 @@ import {
 } from 'vue'
 import { useOwnedAttrs } from '../../../internal/ownedAttrs'
 import { useInteractiveLeafRegistration } from '../../../internal/passiveContentContract'
+import {
+  validateBoolean,
+  validateBoundedNumber,
+  validateExactString,
+} from '../../../internal/runtimeContract'
+import type {
+  SVirtualListAlignment,
+  SVirtualListAnchor,
+  SVirtualListViewportSnapshot,
+  SVirtualListVisibleRange,
+} from './SVirtualList'
 defineOptions({ inheritAttrs: false })
 
-type Alignment = 'auto' | 'start' | 'center' | 'end'
 type StyleObject = Record<string, string>
+type ScrollIntent = 'up' | 'down' | 'unknown' | null
 
 const props = withDefaults(defineProps<SVirtualListProps<T>>(), {
   overscan: 8,
   height: null,
   externalScrollTarget: null,
+  followTail: false,
+  nearStartThreshold: 80,
+  endThreshold: 24,
+  semanticRole: 'list',
+  live: 'off',
+  busy: false,
 })
 
+const emit = defineEmits<{
+  (event: 'update:followTail', value: boolean): void
+  (event: 'viewport-change', state: SVirtualListViewportState): void
+  (event: 'near-start', state: SVirtualListViewportState): void
+}>()
+
 defineSlots<{
   default(props: { item: T; index: number; position: number; setSize: number }): unknown
 }>()
@@ -91,6 +133,37 @@ const renderedItemKeysByElement = new Map<HTMLElement, SVirtualListItemKey>()
 const renderedItemRefs = new Map<SVirtualListItemKey, VNodeRef>()
 let resizeObserver: ResizeObserver | null = null
 let boundExternalTarget: HTMLElement | null = null
+let scrollIntent: ScrollIntent = null
+let pointerOwnsScrollbar = false
+let lastNearStart = false
+let lastPublishedState = ''
+const followTailIntent = ref(props.followTail)
+
+const validatedSemanticRole = computed<SVirtualListSemanticRole>(() => validateExactString(
+  'SVirtualList',
+  'semanticRole',
+  props.semanticRole,
+  ['list', 'log'] as const,
+))
+const validatedLive = computed<SVirtualListLiveMode>(() => validateExactString(
+  'SVirtualList',
+  'live',
+  props.live,
+  ['off', 'polite', 'assertive'] as const,
+))
+const validatedBusy = computed(() => validateBoolean('SVirtualList', 'busy', props.busy))
+const validatedNearStartThreshold = computed(() => validateBoundedNumber(
+  'SVirtualList',
+  'nearStartThreshold',
+  props.nearStartThreshold,
+  { minimum: 0, maximum: 10_000 },
+))
+const validatedEndThreshold = computed(() => validateBoundedNumber(
+  'SVirtualList',
+  'endThreshold',
+  props.endThreshold,
+  { minimum: 0, maximum: 10_000 },
+))
 
 const isExternal = computed(() => props.externalScrollTarget !== null)
 
@@ -199,17 +272,151 @@ function externalOffset(): number {
   return root.getBoundingClientRect().top - target.getBoundingClientRect().top + target.scrollTop
 }
 
+function scrollOwner(): HTMLElement | null {
+  return props.externalScrollTarget ?? container.value
+}
+
+function maximumScrollOffset(): number {
+  return Math.max(0, totalHeight.value - viewportHeight.value)
+}
+
+function currentAnchor(keys: readonly SVirtualListItemKey[] = itemKeys.value): SVirtualListAnchor | null {
+  if (keys.length === 0) return null
+  const sizes = keys.map((key) => measurements.value.get(key) ?? props.itemSize)
+  let accumulated = 0
+  let index = 0
+  const viewportOffset = Math.max(0, scrollTop.value)
+  while (index < sizes.length - 1 && accumulated + (sizes[index] ?? props.itemSize) <= viewportOffset) {
+    accumulated += sizes[index] ?? props.itemSize
+    index += 1
+  }
+  const key = keys[index]
+  if (key === undefined) return null
+  return { key, offset: viewportOffset - accumulated }
+}
+
+function visibleRange(): SVirtualListVisibleRange {
+  if (props.items.length === 0) {
+    return { firstIndex: -1, lastIndex: -1, firstKey: null, lastKey: null }
+  }
+  const firstIndex = firstVisibleIndex.value
+  const lastIndex = Math.max(firstIndex, lastVisibleIndex.value)
+  return {
+    firstIndex,
+    lastIndex,
+    firstKey: itemKeys.value[firstIndex] ?? null,
+    lastKey: itemKeys.value[lastIndex] ?? null,
+  }
+}
+
+function getViewportState(): SVirtualListViewportState {
+  const nearStart = scrollTop.value <= validatedNearStartThreshold.value
+  const atEnd = maximumScrollOffset() - scrollTop.value <= validatedEndThreshold.value
+  return {
+    anchor: currentAnchor(),
+    visibleRange: visibleRange(),
+    nearStart,
+    atEnd,
+    pinnedToEnd: followTailIntent.value,
+  }
+}
+
+function publishViewportState(): void {
+  const state = getViewportState()
+  const signature = JSON.stringify(state)
+  if (signature !== lastPublishedState) {
+    lastPublishedState = signature
+    emit('viewport-change', state)
+  }
+  if (state.nearStart && !lastNearStart) emit('near-start', state)
+  lastNearStart = state.nearStart
+}
+
+function setFollowTail(value: boolean): void {
+  const validated = validateBoolean('SVirtualList', 'setFollowTail value', value)
+  if (followTailIntent.value === validated) return
+  followTailIntent.value = validated
+  emit('update:followTail', validated)
+  publishViewportState()
+}
+
 function updateViewport(): void {
-  const target = props.externalScrollTarget ?? container.value
+  const target = scrollOwner()
   if (!target) return
   viewportHeight.value = target.clientHeight
   scrollTop.value = Math.max(0, target.scrollTop - (isExternal.value ? externalOffset() : 0))
+  if (scrollIntent === 'up') setFollowTail(false)
+  if (scrollIntent === 'down' && maximumScrollOffset() - scrollTop.value <= validatedEndThreshold.value) {
+    setFollowTail(true)
+  }
+  scrollIntent = null
+  publishViewportState()
 }
 
-function preserveAnchor(index: number, delta: number): void {
-  if (index >= firstVisibleIndex.value || delta === 0) return
-  const target = props.externalScrollTarget ?? container.value
-  if (target) target.scrollTop += delta
+function handleWheel(event: WheelEvent): void {
+  if (event.deltaY < 0) {
+    scrollIntent = 'up'
+    setFollowTail(false)
+  } else if (event.deltaY > 0) {
+    scrollIntent = 'down'
+  }
+}
+
+function handleKeydown(event: KeyboardEvent): void {
+  if (['ArrowUp', 'PageUp', 'Home'].includes(event.key)) {
+    scrollIntent = 'up'
+    setFollowTail(false)
+  } else if (['ArrowDown', 'PageDown', 'End'].includes(event.key)) {
+    scrollIntent = 'down'
+  }
+}
+
+function eventOwnsScrollbar(event: PointerEvent): boolean {
+  const target = scrollOwner()
+  if (!target || event.currentTarget !== target) return false
+  return event.offsetX >= target.clientWidth || event.offsetY >= target.clientHeight
+}
+
+function handlePointerDown(event: PointerEvent): void {
+  pointerOwnsScrollbar = eventOwnsScrollbar(event)
+  if (!pointerOwnsScrollbar) return
+  scrollIntent = 'unknown'
+  setFollowTail(false)
+}
+
+function handlePointerUp(): void {
+  if (!pointerOwnsScrollbar) return
+  pointerOwnsScrollbar = false
+  if (maximumScrollOffset() - scrollTop.value <= validatedEndThreshold.value) setFollowTail(true)
+  scrollIntent = null
+}
+
+function restoreAnchor(anchor: SVirtualListAnchor, failWhenMissing: boolean): boolean {
+  const index = itemKeyIndexes.value.get(anchor.key)
+  if (index === undefined) {
+    if (failWhenMissing) {
+      throw new RangeError(`SVirtualList cannot restore missing anchor key ${describeItemKey(anchor.key)}`)
+    }
+    return false
+  }
+  const target = scrollOwner()
+  if (!target) return false
+  const rowSize = itemSizes.value[index] ?? props.itemSize
+  if (!Number.isFinite(anchor.offset) || anchor.offset < 0) {
+    throw new RangeError(
+      `SVirtualList anchor offset ${anchor.offset} is outside row ${describeItemKey(anchor.key)} size ${rowSize}`,
+    )
+  }
+  if (failWhenMissing && anchor.offset >= rowSize) {
+    throw new RangeError(
+      `SVirtualList anchor offset ${anchor.offset} is outside row ${describeItemKey(anchor.key)} size ${rowSize}`,
+    )
+  }
+  const resolvedOffset = Math.min(anchor.offset, Math.max(0, rowSize - 1))
+  const nextOffset = (offsets.value[index] ?? 0) + resolvedOffset
+  target.scrollTop = Math.max(0, nextOffset + (isExternal.value ? externalOffset() : 0))
+  updateViewport()
+  return true
 }
 
 function unregisterRenderedItem(key: SVirtualListItemKey): void {
@@ -264,32 +471,38 @@ function renderedItemRef(key: SVirtualListItemKey): VNodeRef {
   return itemRef
 }
 
-function measureEntry(entry: ResizeObserverEntry): void {
-  if (entry.target === container.value || entry.target === props.externalScrollTarget) {
-    updateViewport()
-    return
-  }
-  if (!(entry.target instanceof HTMLElement)) {
-    throw new TypeError('SVirtualList received a ResizeObserver entry for a non-HTMLElement target')
-  }
-  const key = renderedItemKeysByElement.get(entry.target)
-  if (key === undefined || renderedItemsByKey.get(key) !== entry.target) {
-    throw new Error('SVirtualList received a ResizeObserver entry for an unregistered rendered item')
-  }
-  const index = itemKeyIndexes.value.get(key)
-  if (index === undefined) {
-    throw new Error(`SVirtualList received a ResizeObserver entry for stale key ${describeItemKey(key)}`)
-  }
-  const size = entry.borderBoxSize[0]?.blockSize ?? entry.contentRect.height
-  if (!Number.isFinite(size) || size <= 0 || measurements.value.get(key) === size) return
-  const previous = measurements.value.get(key) ?? props.itemSize
+function measureEntries(entries: readonly ResizeObserverEntry[]): void {
+  let viewportChanged = false
+  const anchor = followTailIntent.value ? null : currentAnchor()
   const next = new Map(measurements.value)
-  next.set(key, size)
-  measurements.value = next
-  preserveAnchor(index, size - previous)
+  let measurementsChanged = false
+  for (const entry of entries) {
+    if (entry.target === container.value || entry.target === props.externalScrollTarget) {
+      viewportChanged = true
+      continue
+    }
+    if (!(entry.target instanceof HTMLElement)) {
+      throw new TypeError('SVirtualList received a ResizeObserver entry for a non-HTMLElement target')
+    }
+    const key = renderedItemKeysByElement.get(entry.target)
+    if (key === undefined || renderedItemsByKey.get(key) !== entry.target) {
+      throw new Error('SVirtualList received a ResizeObserver entry for an unregistered rendered item')
+    }
+    if (itemKeyIndexes.value.get(key) === undefined) {
+      throw new Error(`SVirtualList received a ResizeObserver entry for stale key ${describeItemKey(key)}`)
+    }
+    const size = entry.borderBoxSize[0]?.blockSize ?? entry.contentRect.height
+    if (!Number.isFinite(size) || size <= 0 || next.get(key) === size) continue
+    next.set(key, size)
+    measurementsChanged = true
+  }
+  if (measurementsChanged) measurements.value = next
+  if (followTailIntent.value && measurementsChanged) scrollToEnd({ follow: true })
+  else if (anchor && measurementsChanged) restoreAnchor(anchor, false)
+  if (viewportChanged || measurementsChanged) updateViewport()
 }
 
-function scrollToIndex(index: number, alignment: Alignment = 'auto'): void {
+function scrollToIndex(index: number, alignment: SVirtualListAlignment = 'auto'): void {
   if (!Number.isInteger(index) || index < 0 || index >= props.items.length) {
     throw new RangeError(`SVirtualList index ${index} is outside 0..${Math.max(props.items.length - 1, 0)}`)
   }
@@ -308,7 +521,48 @@ function scrollToIndex(index: number, alignment: Alignment = 'auto'): void {
   updateViewport()
 }
 
-async function focusItem(index: number, alignment: Alignment = 'auto'): Promise<void> {
+function scrollToKey(key: SVirtualListItemKey, alignment: SVirtualListAlignment = 'auto'): void {
+  const index = itemKeyIndexes.value.get(key)
+  if (index === undefined) {
+    throw new RangeError(`SVirtualList cannot scroll to missing key ${describeItemKey(key)}`)
+  }
+  scrollToIndex(index, alignment)
+}
+
+function scrollToEnd(options: { follow?: boolean } = {}): void {
+  const target = scrollOwner()
+  if (!target) return
+  if (options.follow ?? true) setFollowTail(true)
+  target.scrollTop = maximumScrollOffset() + (isExternal.value ? externalOffset() : 0)
+  updateViewport()
+}
+
+function captureViewport(): SVirtualListViewportSnapshot {
+  return {
+    anchor: currentAnchor(),
+    followTail: followTailIntent.value,
+  }
+}
+
+async function restoreViewport(snapshot: SVirtualListViewportSnapshot): Promise<void> {
+  if (snapshot === null || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+    throw new TypeError('SVirtualList restoreViewport snapshot must be an object')
+  }
+  const followTail = validateBoolean('SVirtualList', 'restoreViewport.followTail', snapshot.followTail)
+  await nextTick()
+  if (followTail) {
+    scrollToEnd({ follow: true })
+    return
+  }
+  if (snapshot.anchor === null) {
+    setFollowTail(false)
+    return
+  }
+  setFollowTail(false)
+  restoreAnchor(snapshot.anchor, true)
+}
+
+async function focusItem(index: number, alignment: SVirtualListAlignment = 'auto'): Promise<void> {
   const key = itemKeys.value[index]
   scrollToIndex(index, alignment)
   await nextTick()
@@ -331,29 +585,53 @@ async function focusItem(index: number, alignment: Alignment = 'auto'): Promise<
   element.focus()
 }
 
-defineExpose({ scrollToIndex, focusItem })
+defineExpose({
+  captureViewport,
+  focusItem,
+  getViewportState,
+  restoreViewport,
+  scrollToEnd,
+  scrollToIndex,
+  scrollToKey,
+  setFollowTail,
+})
 
 function bindExternalTarget(target: HTMLElement | null): void {
   boundExternalTarget?.removeEventListener('scroll', updateViewport)
+  boundExternalTarget?.removeEventListener('wheel', handleWheel)
+  boundExternalTarget?.removeEventListener('keydown', handleKeydown)
+  boundExternalTarget?.removeEventListener('pointerdown', handlePointerDown)
+  boundExternalTarget?.removeEventListener('pointerup', handlePointerUp)
   if (boundExternalTarget) resizeObserver?.unobserve(boundExternalTarget)
   boundExternalTarget = target
   boundExternalTarget?.addEventListener('scroll', updateViewport, { passive: true })
+  boundExternalTarget?.addEventListener('wheel', handleWheel, { passive: true })
+  boundExternalTarget?.addEventListener('keydown', handleKeydown)
+  boundExternalTarget?.addEventListener('pointerdown', handlePointerDown)
+  boundExternalTarget?.addEventListener('pointerup', handlePointerUp)
   if (boundExternalTarget) resizeObserver?.observe(boundExternalTarget)
   updateViewport()
 }
 
 onMounted(() => {
   if (typeof ResizeObserver !== 'undefined') {
-    resizeObserver = new ResizeObserver((entries) => entries.forEach(measureEntry))
+    resizeObserver = new ResizeObserver((entries) => measureEntries(entries))
     if (container.value) resizeObserver.observe(container.value)
     for (const element of renderedItemsByKey.values()) resizeObserver.observe(element)
   }
   bindExternalTarget(props.externalScrollTarget)
   updateViewport()
+  if (followTailIntent.value) void nextTick(() => scrollToEnd({ follow: true }))
 })
 
 watch(() => props.externalScrollTarget, bindExternalTarget)
-watch(() => itemKeys.value, (keys) => {
+watch(() => props.followTail, (value) => {
+  followTailIntent.value = validateBoolean('SVirtualList', 'followTail', value)
+  if (followTailIntent.value) void nextTick(() => scrollToEnd({ follow: false }))
+  else publishViewportState()
+})
+watch(() => itemKeys.value, async (keys, previousKeys) => {
+  const anchor = followTailIntent.value ? null : currentAnchor(previousKeys)
   const activeKeys = new Set(keys)
   measurements.value = new Map([...measurements.value].filter(([key]) => activeKeys.has(key)))
   for (const key of renderedItemsByKey.keys()) {
@@ -362,11 +640,18 @@ watch(() => itemKeys.value, (keys) => {
   for (const key of renderedItemRefs.keys()) {
     if (!activeKeys.has(key)) renderedItemRefs.delete(key)
   }
+  await nextTick()
+  if (followTailIntent.value) scrollToEnd({ follow: true })
+  else if (anchor) restoreAnchor(anchor, false)
   updateViewport()
 })
 
 onBeforeUnmount(() => {
   boundExternalTarget?.removeEventListener('scroll', updateViewport)
+  boundExternalTarget?.removeEventListener('wheel', handleWheel)
+  boundExternalTarget?.removeEventListener('keydown', handleKeydown)
+  boundExternalTarget?.removeEventListener('pointerdown', handlePointerDown)
+  boundExternalTarget?.removeEventListener('pointerup', handlePointerUp)
   resizeObserver?.disconnect()
   renderedItemsByKey.clear()
   renderedItemKeysByElement.clear()

package/src/styles/tokens.css

@@ -116,6 +116,9 @@
   --s-control-hitbox-md: 2.5rem;
   --s-control-hitbox-lg: 3rem;
   --s-control-indicator-size: 1.25rem;
+  --s-resize-handle-hitbox-compact: 0.375rem;
+  --s-resize-handle-hitbox-standard: 0.75rem;
+  --s-resize-handle-hitbox-spacious: 2rem;
   --s-icon-size-2xs: 0.75rem;
   --s-icon-size-xs: 1rem;
   --s-icon-size-sm: 1.25rem;