@pgcorp/ui-kit 0.8.0 → 0.9.0

package/src/components/shared/data-display/SActionListItem.css

@@ -1,9 +1,8 @@
 @reference "../../../styles/reference.css";
 
 .s-action-list-item {
-  @apply grid min-h-12 min-w-0 items-center gap-2;
+  @apply min-h-12 min-w-0;
   height: max-content;
-  grid-template-columns: minmax(0, 1fr) auto;
 }
 
 .s-action-list-item[data-height-mode='fill'] {
@@ -94,7 +93,7 @@
 .s-action-list-item[data-density='compact'] .s-action-list-item__icon { @apply h-7 w-7; }
 
 .s-action-list-item[data-trailing-layout='stacked'] {
-  grid-template-columns: minmax(0, 1fr);
+  @apply w-full;
 }
 
 .s-action-list-item[data-trailing-layout='stacked'] .s-action-list-item__trailing {
@@ -103,12 +102,12 @@
 }
 
 @container (max-width: 32rem) {
-  .s-action-list-item[data-trailing-layout='responsive'] {
-    grid-template-columns: minmax(0, 1fr);
-  }
-
   .s-action-list-item[data-trailing-layout='responsive'] .s-action-list-item__trailing {
-    @apply w-full justify-end pb-2 pr-2;
+    @apply w-full flex-wrap justify-end gap-y-1 pb-2 pr-2;
     padding-left: calc(3.5rem + var(--s-action-list-item-indent));
   }
+
+  .s-action-list-item[data-trailing-layout='responsive'] .s-action-list-item__trailing > * {
+    max-width: 100%;
+  }
 }

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

@@ -194,6 +194,7 @@ function emitAction(event: MouseEvent): void {
       :padding="surfacePadding"
       :radius="surfaceRadius"
       :fill="heightMode === 'fill' ? 'container' : 'content'"
+      :actions-layout="trailingLayout"
       @activate="emit('activate', $event)"
     >
       <div class="s-action-list-item__main" :class="{ 's-action-list-item__main--static': resolvedMode === 'static' }">
@@ -212,25 +213,27 @@ function emitAction(event: MouseEvent): void {
           </span>
         </span>
       </div>
+      <template v-if="hasTrailing" #actions>
+        <div class="s-action-list-item__trailing">
+          <slot name="status" />
+          <SBadge v-if="statusLabel" :severity="statusSeverity">{{ statusLabel }}</SBadge>
+          <SBadge v-for="badge in validatedBadges" :key="badge.id" :severity="badge.severity">
+            {{ badge.label }}
+          </SBadge>
+          <SButton
+            v-if="actionLabel"
+            size="sm"
+            :label="actionLabel"
+            :leading-icon="actionIcon"
+            :severity="actionSeverity"
+            :disabled="surfaceDisabled || actionDisabled"
+            @click="emitAction"
+          />
+          <slot name="actions" :disabled="surfaceDisabled || actionDisabled" :emit-action="emitAction" />
+          <component :is="trailingIcon" v-if="trailingIcon" class="s-action-list-item__trailing-icon" aria-hidden="true" />
+        </div>
+      </template>
     </SActionCard>
-    <div v-if="hasTrailing" class="s-action-list-item__trailing">
-      <slot name="status" />
-      <SBadge v-if="statusLabel" :severity="statusSeverity">{{ statusLabel }}</SBadge>
-      <SBadge v-for="badge in validatedBadges" :key="badge.id" :severity="badge.severity">
-        {{ badge.label }}
-      </SBadge>
-      <SButton
-        v-if="actionLabel"
-        size="sm"
-        :label="actionLabel"
-        :leading-icon="actionIcon"
-        :severity="actionSeverity"
-        :disabled="surfaceDisabled || actionDisabled"
-        @click="emitAction"
-      />
-      <slot name="actions" :disabled="surfaceDisabled || actionDisabled" :emit-action="emitAction" />
-      <component :is="trailingIcon" v-if="trailingIcon" class="s-action-list-item__trailing-icon" aria-hidden="true" />
-    </div>
   </div>
 </template>
 

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

@@ -352,7 +352,7 @@ watchEffect(() => {
             :y="tick.position"
             text-anchor="end"
             dominant-baseline="middle"
-          >{{ tick.label }}</text>
+          >{{ tick.displayLabel }}<title v-if="tick.displayLabel !== tick.label">{{ tick.label }}</title></text>
           <text
             v-if="validatedYAxisLabel"
             class="s-chart__axis-title"
@@ -369,7 +369,7 @@ watchEffect(() => {
             :key="category.key"
             :x="category.x"
             :y="model.plotY + model.plotHeight + 18"
-            text-anchor="middle"
+            :text-anchor="category.textAnchor"
           >
             <tspan
               v-for="(line, lineIndex) in category.lines"

package/src/components/shared/data-display/SChip.css

@@ -8,12 +8,17 @@
 .s-chip[data-mode='action']:not([data-s-pill-disabled='true']),
 .s-chip[data-mode='link']:not([data-s-pill-disabled='true']) {
   @apply cursor-pointer;
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, currentColor 42%, transparent);
   transition:
-    filter var(--s-motion-standard) ease,
     box-shadow var(--s-motion-standard) ease;
 }
 
 .s-chip[data-mode='action']:not([data-s-pill-disabled='true']):hover,
 .s-chip[data-mode='link']:not([data-s-pill-disabled='true']):hover {
-  filter: brightness(0.96);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, currentColor 68%, transparent);
+}
+
+.s-chip[data-mode='action']:active,
+.s-chip[data-mode='link']:active {
+  box-shadow: inset 0 0 0 1px currentColor;
 }

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

@@ -38,8 +38,7 @@
         :capabilities="editorCapabilities"
         :read-only="validatedReadOnly"
         :viewport="validatedViewport"
-        :aria-label="props.ariaLabel"
-        :aria-labelledby="props.ariaLabelledby"
+        v-bind="editorAccessibleName"
         :placeholder="props.placeholder"
         :next-selection-pos="props.nextSelectionPos"
         @update:model-value="emit('update:code', $event)"
@@ -137,6 +136,9 @@ const codeEditor = ref<InstanceType<typeof import('./SCodeEditor.vue')['default'
 const plainSurface = ref<HTMLElement | null>(null);
 const AsyncSCodeEditor = defineAsyncComponent(() => import('../../../internal/lazyCodeEditor'));
 const ownedAttrs = useOwnedAttrs({ component: 'SCodeBlock', owner: 'code block root' });
+const editorAccessibleName = computed<AccessibleName>(() => props.ariaLabel !== undefined
+  ? { ariaLabel: props.ariaLabel }
+  : { ariaLabelledby: props.ariaLabelledby });
 const emit = defineEmits<{
   (e: 'cursor-activity', payload: { pos: number; lineFrom: number; lineTo: number; lineText: string; cursorCol: number }): void
   (e: 'update:code', value: string): void

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

@@ -1,4 +1,37 @@
 /** Ключ элемента виртуального списка. / Virtual-list item key. */
 export type SVirtualListItemKey = string | number
 
+/** Выравнивание явного перехода к строке. / Alignment for explicit row navigation. */
+export type SVirtualListAlignment = 'auto' | 'start' | 'center' | 'end'
+
+/** Устойчивый viewport anchor: доменный key и смещение внутри строки. */
+export interface SVirtualListAnchor {
+  key: SVirtualListItemKey
+  offset: number
+}
+
+export interface SVirtualListVisibleRange {
+  firstIndex: number
+  lastIndex: number
+  firstKey: SVirtualListItemKey | null
+  lastKey: SVirtualListItemKey | null
+}
+
+export interface SVirtualListViewportState {
+  anchor: SVirtualListAnchor | null
+  visibleRange: SVirtualListVisibleRange
+  nearStart: boolean
+  atEnd: boolean
+  pinnedToEnd: boolean
+}
+
+/** Сериализуемый снимок позиции для переключения между keyed collections. */
+export interface SVirtualListViewportSnapshot {
+  anchor: SVirtualListAnchor | null
+  followTail: boolean
+}
+
+export type SVirtualListSemanticRole = 'list' | 'log'
+export type SVirtualListLiveMode = 'off' | 'polite' | 'assertive'
+
 export type { SVirtualListProps } from './SVirtualList.vue'

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()