@wyxos/vibe 1.6.22 → 1.6.24

package/src/useMasonryPagination.ts

@@ -0,0 +1,342 @@
+import { ref, type Ref } from 'vue'
+import { normalizeError } from './utils/errorHandler'
+
+export interface UseMasonryPaginationOptions {
+  getNextPage: (page: any) => Promise<{ items: any[]; nextPage: any }>
+  masonry: Ref<any[]>
+  isLoading: Ref<boolean>
+  hasReachedEnd: Ref<boolean>
+  loadError: Ref<Error | null>
+  currentPage: Ref<any>
+  paginationHistory: Ref<any[]>
+  refreshLayout: (items: any[]) => void
+  retryMaxAttempts: number
+  retryInitialDelayMs: number
+  retryBackoffStepMs: number
+  backfillEnabled: boolean
+  backfillDelayMs: number
+  backfillMaxCalls: number
+  pageSize: number
+  autoRefreshOnEmpty: boolean
+  emits: {
+    (event: 'retry:start', payload: { attempt: number; max: number; totalMs: number }): void
+    (event: 'retry:tick', payload: { attempt: number; remainingMs: number; totalMs: number }): void
+    (event: 'retry:stop', payload: { attempt: number; success: boolean }): void
+    (event: 'backfill:start', payload: { target: number; fetched: number; calls: number }): void
+    (event: 'backfill:tick', payload: { fetched: number; target: number; calls: number; remainingMs: number; totalMs: number }): void
+    (event: 'backfill:stop', payload: { fetched: number; calls: number; cancelled?: boolean }): void
+  }
+}
+
+export function useMasonryPagination(options: UseMasonryPaginationOptions) {
+  const {
+    getNextPage,
+    masonry,
+    isLoading,
+    hasReachedEnd,
+    loadError,
+    currentPage,
+    paginationHistory,
+    refreshLayout,
+    retryMaxAttempts,
+    retryInitialDelayMs,
+    retryBackoffStepMs,
+    backfillEnabled,
+    backfillDelayMs,
+    backfillMaxCalls,
+    pageSize,
+    autoRefreshOnEmpty,
+    emits
+  } = options
+
+  const cancelRequested = ref(false)
+  let backfillActive = false
+
+  function waitWithProgress(totalMs: number, onTick: (remaining: number, total: number) => void) {
+    return new Promise<void>((resolve) => {
+      const total = Math.max(0, totalMs | 0)
+      const start = Date.now()
+      onTick(total, total)
+      const id = setInterval(() => {
+        // Check for cancellation
+        if (cancelRequested.value) {
+          clearInterval(id)
+          resolve()
+          return
+        }
+        const elapsed = Date.now() - start
+        const remaining = Math.max(0, total - elapsed)
+        onTick(remaining, total)
+        if (remaining <= 0) {
+          clearInterval(id)
+          resolve()
+        }
+      }, 100)
+    })
+  }
+
+  async function fetchWithRetry<T = any>(fn: () => Promise<T>): Promise<T> {
+    let attempt = 0
+    const max = retryMaxAttempts
+    let delay = retryInitialDelayMs
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      try {
+        const res = await fn()
+        if (attempt > 0) {
+          emits('retry:stop', { attempt, success: true })
+        }
+        return res
+      } catch (err) {
+        attempt++
+        if (attempt > max) {
+          emits('retry:stop', { attempt: attempt - 1, success: false })
+          throw err
+        }
+        emits('retry:start', { attempt, max, totalMs: delay })
+        await waitWithProgress(delay, (remaining, total) => {
+          emits('retry:tick', { attempt, remainingMs: remaining, totalMs: total })
+        })
+        delay += retryBackoffStepMs
+      }
+    }
+  }
+
+  async function getContent(page: number) {
+    try {
+      const response = await fetchWithRetry(() => getNextPage(page))
+      refreshLayout([...masonry.value, ...response.items])
+      return response
+    } catch (error) {
+      // Error is handled by callers (loadPage, loadNext, etc.) which set loadError
+      throw error
+    }
+  }
+
+  async function maybeBackfillToTarget(baselineCount: number, force = false) {
+    if (!force && !backfillEnabled) return
+    if (backfillActive) return
+    if (cancelRequested.value) return
+    // Don't backfill if we've reached the end
+    if (hasReachedEnd.value) return
+
+    const targetCount = (baselineCount || 0) + (pageSize || 0)
+    if (!pageSize || pageSize <= 0) return
+
+    const lastNext = paginationHistory.value[paginationHistory.value.length - 1]
+    if (lastNext == null) {
+      hasReachedEnd.value = true
+      return
+    }
+
+    if (masonry.value.length >= targetCount) return
+
+    backfillActive = true
+    // Set loading to true at the start of backfill and keep it true throughout
+    isLoading.value = true
+    try {
+      let calls = 0
+      emits('backfill:start', { target: targetCount, fetched: masonry.value.length, calls })
+
+      while (
+        masonry.value.length < targetCount &&
+        calls < backfillMaxCalls &&
+        paginationHistory.value[paginationHistory.value.length - 1] != null &&
+        !cancelRequested.value &&
+        !hasReachedEnd.value &&
+        backfillActive
+      ) {
+        await waitWithProgress(backfillDelayMs, (remaining, total) => {
+          emits('backfill:tick', {
+            fetched: masonry.value.length,
+            target: targetCount,
+            calls,
+            remainingMs: remaining,
+            totalMs: total
+          })
+        })
+
+        if (cancelRequested.value || !backfillActive) break
+
+        const currentPage = paginationHistory.value[paginationHistory.value.length - 1]
+        if (currentPage == null) {
+          hasReachedEnd.value = true
+          break
+        }
+        try {
+          // Don't toggle isLoading here - keep it true throughout backfill
+          // Check cancellation before starting getContent to avoid unnecessary requests
+          if (cancelRequested.value || !backfillActive) break
+          const response = await getContent(currentPage)
+          if (cancelRequested.value || !backfillActive) break
+          // Clear error on successful load
+          loadError.value = null
+          paginationHistory.value.push(response.nextPage)
+          // Update hasReachedEnd if nextPage is null
+          if (response.nextPage == null) {
+            hasReachedEnd.value = true
+          }
+        } catch (error) {
+          // Set load error but don't break the backfill loop unless cancelled
+          if (cancelRequested.value || !backfillActive) break
+          loadError.value = normalizeError(error)
+        }
+
+        calls++
+      }
+
+      emits('backfill:stop', { fetched: masonry.value.length, calls })
+    } finally {
+      backfillActive = false
+      // Only set loading to false when backfill completes or is cancelled
+      isLoading.value = false
+    }
+  }
+
+  async function loadPage(page: number) {
+    if (isLoading.value) return
+    // Starting a new load should clear any previous cancel request
+    cancelRequested.value = false
+    isLoading.value = true
+    // Reset hasReachedEnd and loadError when loading a new page
+    hasReachedEnd.value = false
+    loadError.value = null
+    try {
+      const baseline = masonry.value.length
+      if (cancelRequested.value) return
+      const response = await getContent(page)
+      if (cancelRequested.value) return
+      // Clear error on successful load
+      loadError.value = null
+      currentPage.value = page  // Track the current page
+      paginationHistory.value.push(response.nextPage)
+      // Update hasReachedEnd if nextPage is null
+      if (response.nextPage == null) {
+        hasReachedEnd.value = true
+      }
+      await maybeBackfillToTarget(baseline)
+      return response
+    } catch (error) {
+      // Set load error - error is handled and exposed to UI via loadError
+      loadError.value = normalizeError(error)
+      throw error
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  async function loadNext() {
+    if (isLoading.value) return
+    // Don't load if we've already reached the end
+    if (hasReachedEnd.value) return
+    // Starting a new load should clear any previous cancel request
+    cancelRequested.value = false
+    isLoading.value = true
+    // Clear error when attempting to load
+    loadError.value = null
+    try {
+      const baseline = masonry.value.length
+      if (cancelRequested.value) return
+      const nextPageToLoad = paginationHistory.value[paginationHistory.value.length - 1]
+      // Don't load if nextPageToLoad is null
+      if (nextPageToLoad == null) {
+        hasReachedEnd.value = true
+        isLoading.value = false
+        return
+      }
+      const response = await getContent(nextPageToLoad)
+      if (cancelRequested.value) return
+      // Clear error on successful load
+      loadError.value = null
+      currentPage.value = nextPageToLoad  // Track the current page
+      paginationHistory.value.push(response.nextPage)
+      // Update hasReachedEnd if nextPage is null
+      if (response.nextPage == null) {
+        hasReachedEnd.value = true
+      }
+      await maybeBackfillToTarget(baseline)
+      return response
+    } catch (error) {
+      // Set load error - error is handled and exposed to UI via loadError
+      loadError.value = normalizeError(error)
+      throw error
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  async function refreshCurrentPage() {
+    if (isLoading.value) return
+    cancelRequested.value = false
+    isLoading.value = true
+
+    try {
+      // Use the tracked current page
+      const pageToRefresh = currentPage.value
+
+      if (pageToRefresh == null) {
+        console.warn('[Masonry] No current page to refresh - currentPage:', currentPage.value, 'paginationHistory:', paginationHistory.value)
+        return
+      }
+
+      // Clear existing items
+      masonry.value = []
+      // Reset end flag when refreshing
+      hasReachedEnd.value = false
+      // Reset error flag when refreshing
+      loadError.value = null
+
+      // Reset pagination history to just the current page
+      paginationHistory.value = [pageToRefresh]
+
+      // Reload the current page
+      const response = await getContent(pageToRefresh)
+      if (cancelRequested.value) return
+
+      // Clear error on successful load
+      loadError.value = null
+      // Update pagination state
+      currentPage.value = pageToRefresh
+      paginationHistory.value.push(response.nextPage)
+      // Update hasReachedEnd if nextPage is null
+      if (response.nextPage == null) {
+        hasReachedEnd.value = true
+      }
+
+      // Optionally backfill if needed
+      const baseline = masonry.value.length
+      await maybeBackfillToTarget(baseline)
+
+      return response
+    } catch (error) {
+      // Set load error - error is handled and exposed to UI via loadError
+      loadError.value = normalizeError(error)
+      throw error
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  function cancelLoad() {
+    const wasBackfilling = backfillActive
+    cancelRequested.value = true
+    isLoading.value = false
+    // Set backfillActive to false to immediately stop backfilling
+    // The backfill loop checks this flag and will exit on the next iteration
+    backfillActive = false
+    // If backfill was active, emit stop event immediately
+    if (wasBackfilling) {
+      emits('backfill:stop', { fetched: masonry.value.length, calls: 0, cancelled: true })
+    }
+  }
+
+  return {
+    loadPage,
+    loadNext,
+    refreshCurrentPage,
+    cancelLoad,
+    maybeBackfillToTarget,
+    getContent
+  }
+}
+

package/src/useMasonryTransitions.ts

@@ -2,7 +2,10 @@
  * Composable for handling masonry item transitions (typed)
  * Optimized for large item arrays by skipping DOM operations for items outside viewport
  */
-export function useMasonryTransitions(refs: { container?: any; masonry?: any }, opts?: { leaveDurationMs?: number }) {
+export function useMasonryTransitions(
+  refs: { container?: any; masonry?: any },
+  opts?: { leaveDurationMs?: number; virtualizing?: { value: boolean } }
+) {
   // Cache viewport bounds to avoid repeated calculations
   let cachedViewportTop = 0
   let cachedViewportBottom = 0
@@ -32,6 +35,19 @@ export function useMasonryTransitions(refs: { container?: any; masonry?: any },
     // Get height from computed style or use a reasonable fallback
     const height = el.offsetHeight || parseInt(getComputedStyle(el).height || '200', 10) || 200
 
+    // Skip animation during virtualization - just set position immediately
+    if (opts?.virtualizing?.value) {
+      el.style.transition = 'none'
+      el.style.opacity = '1'
+      el.style.transform = `translate3d(${left}px, ${top}px, 0) scale(1)`
+      el.style.removeProperty('--masonry-opacity-delay')
+      requestAnimationFrame(() => {
+        el.style.transition = ''
+        done()
+      })
+      return
+    }
+
     // Skip animation for items outside viewport - just set position immediately
     if (!isItemInViewport(top, height)) {
       el.style.opacity = '1'
@@ -64,6 +80,16 @@ export function useMasonryTransitions(refs: { container?: any; masonry?: any },
   function onBeforeEnter(el: HTMLElement) {
     const left = parseInt(el.dataset.left || '0', 10)
     const top = parseInt(el.dataset.top || '0', 10)
+    
+    // Skip animation during virtualization
+    if (opts?.virtualizing?.value) {
+      el.style.transition = 'none'
+      el.style.opacity = '1'
+      el.style.transform = `translate3d(${left}px, ${top}px, 0) scale(1)`
+      el.style.removeProperty('--masonry-opacity-delay')
+      return
+    }
+    
     el.style.opacity = '0'
     el.style.transform = `translate3d(${left}px, ${top + 10}px, 0) scale(0.985)`
   }
@@ -73,6 +99,12 @@ export function useMasonryTransitions(refs: { container?: any; masonry?: any },
     const top = parseInt(el.dataset.top || '0', 10)
     const height = el.offsetHeight || parseInt(getComputedStyle(el).height || '200', 10) || 200
 
+    // Skip animation during virtualization
+    if (opts?.virtualizing?.value) {
+      // no-op; removal will be immediate in leave
+      return
+    }
+
     // Skip animation for items outside viewport
     if (!isItemInViewport(top, height)) {
       el.style.transition = 'none'
@@ -94,6 +126,12 @@ export function useMasonryTransitions(refs: { container?: any; masonry?: any },
     const top = parseInt(el.dataset.top || '0', 10)
     const height = el.offsetHeight || parseInt(getComputedStyle(el).height || '200', 10) || 200
 
+    // Skip animation during virtualization - remove immediately
+    if (opts?.virtualizing?.value) {
+      done()
+      return
+    }
+
     // Skip animation for items outside viewport - remove immediately
     if (!isItemInViewport(top, height)) {
       el.style.transition = 'none'

package/src/useMasonryVirtualization.ts

@@ -0,0 +1,140 @@
+import { ref, computed, nextTick, type Ref, type ComputedRef } from 'vue'
+import { calculateColumnHeights } from './masonryUtils'
+
+export interface UseMasonryVirtualizationOptions {
+  masonry: Ref<any[]>
+  container: Ref<HTMLElement | null>
+  columns: Ref<number>
+  virtualBufferPx: number
+  loadThresholdPx: number
+  handleScroll: (precomputedHeights?: number[]) => void
+}
+
+export function useMasonryVirtualization(options: UseMasonryVirtualizationOptions) {
+  const {
+    masonry,
+    container,
+    columns,
+    virtualBufferPx,
+    loadThresholdPx
+  } = options
+
+  // Use a ref for handleScroll so it can be updated after initialization
+  const handleScrollRef = ref<(precomputedHeights?: number[]) => void>(options.handleScroll)
+
+  // Virtualization viewport state
+  const viewportTop = ref(0)
+  const viewportHeight = ref(0)
+  const VIRTUAL_BUFFER_PX = virtualBufferPx
+
+  // Gate transitions during virtualization-only DOM churn
+  const virtualizing = ref(false)
+
+  // Scroll progress tracking
+  const scrollProgress = ref<{ distanceToTrigger: number; isNearTrigger: boolean }>({
+    distanceToTrigger: 0,
+    isNearTrigger: false
+  })
+
+  // Visible window of items (virtualization)
+  const visibleMasonry = computed(() => {
+    const top = viewportTop.value - VIRTUAL_BUFFER_PX
+    const bottom = viewportTop.value + viewportHeight.value + VIRTUAL_BUFFER_PX
+    const items = masonry.value as any[]
+    if (!items || items.length === 0) return [] as any[]
+
+    // Filter items that have valid positions and are within viewport
+    const visible = items.filter((it: any) => {
+      // If item doesn't have position yet, include it (will be filtered once layout is calculated)
+      if (typeof it.top !== 'number' || typeof it.columnHeight !== 'number') {
+        return true // Include items without positions to avoid hiding them prematurely
+      }
+      const itemTop = it.top
+      const itemBottom = it.top + it.columnHeight
+      return itemBottom >= top && itemTop <= bottom
+    })
+
+    // Log if we're filtering out items (for debugging)
+    if (import.meta.env.DEV && items.length > 0 && visible.length === 0 && viewportHeight.value > 0) {
+      const itemsWithPositions = items.filter((it: any) =>
+        typeof it.top === 'number' && typeof it.columnHeight === 'number'
+      )
+    }
+
+    return visible
+  })
+
+  function updateScrollProgress(precomputedHeights?: number[]) {
+    if (!container.value) return
+
+    const { scrollTop, clientHeight } = container.value
+    const visibleBottom = scrollTop + clientHeight
+
+    const columnHeights = precomputedHeights ?? calculateColumnHeights(masonry.value as any, columns.value)
+    const tallest = columnHeights.length ? Math.max(...columnHeights) : 0
+    const threshold = typeof loadThresholdPx === 'number' ? loadThresholdPx : 200
+    const triggerPoint = threshold >= 0
+      ? Math.max(0, tallest - threshold)
+      : Math.max(0, tallest + threshold)
+
+    const distanceToTrigger = Math.max(0, triggerPoint - visibleBottom)
+    const isNearTrigger = distanceToTrigger <= 100
+
+    scrollProgress.value = {
+      distanceToTrigger: Math.round(distanceToTrigger),
+      isNearTrigger
+    }
+  }
+
+  async function updateViewport() {
+    if (container.value) {
+      const scrollTop = container.value.scrollTop
+      const clientHeight = container.value.clientHeight || window.innerHeight
+      // Ensure viewportHeight is never 0 (fallback to window height if container height is 0)
+      const safeClientHeight = clientHeight > 0 ? clientHeight : window.innerHeight
+      viewportTop.value = scrollTop
+      viewportHeight.value = safeClientHeight
+      // Log when scroll handler runs (helpful for debugging viewport issues)
+      if (import.meta.env.DEV) {
+        console.log('[Masonry] scroll: viewport updated', {
+          scrollTop,
+          clientHeight: safeClientHeight,
+          itemsCount: masonry.value.length,
+          visibleItemsCount: visibleMasonry.value.length
+        })
+      }
+    }
+    // Gate transitions for virtualization-only DOM changes
+    virtualizing.value = true
+    await nextTick()
+    await new Promise<void>(r => requestAnimationFrame(() => r()))
+    virtualizing.value = false
+
+    const heights = calculateColumnHeights(masonry.value as any, columns.value)
+    handleScrollRef.value(heights as any)
+    updateScrollProgress(heights)
+  }
+
+  function reset() {
+    viewportTop.value = 0
+    viewportHeight.value = 0
+    virtualizing.value = false
+    scrollProgress.value = {
+      distanceToTrigger: 0,
+      isNearTrigger: false
+    }
+  }
+
+  return {
+    viewportTop,
+    viewportHeight,
+    virtualizing,
+    scrollProgress,
+    visibleMasonry,
+    updateScrollProgress,
+    updateViewport,
+    reset,
+    handleScroll: handleScrollRef
+  }
+}
+