@wyxos/vibe 1.6.25 → 1.6.27

package/lib/vibe.css

@@ -1 +1 @@
-.masonry-container[data-v-2c2a4c76]{overflow-anchor:none}.masonry-item[data-v-2c2a4c76]{will-change:transform,opacity;contain:layout paint;transition:transform var(--masonry-duration, .45s) var(--masonry-ease, cubic-bezier(.22, .61, .36, 1)),opacity var(--masonry-leave-duration, .16s) ease-out var(--masonry-opacity-delay, 0ms);backface-visibility:hidden}.masonry-move[data-v-2c2a4c76]{transition:transform var(--masonry-duration, .45s) var(--masonry-ease, cubic-bezier(.22, .61, .36, 1))}@media (prefers-reduced-motion: reduce){.masonry-container:not(.force-motion) .masonry-item[data-v-2c2a4c76],.masonry-container:not(.force-motion) .masonry-move[data-v-2c2a4c76]{transition-duration:1ms!important}}
+.masonry-container[data-v-ce75570c]{overflow-anchor:none}.masonry-item[data-v-ce75570c]{will-change:transform,opacity;contain:layout paint;transition:transform var(--masonry-duration, .45s) var(--masonry-ease, cubic-bezier(.22, .61, .36, 1)),opacity var(--masonry-leave-duration, .16s) ease-out var(--masonry-opacity-delay, 0ms);backface-visibility:hidden}.masonry-move[data-v-ce75570c]{transition:transform var(--masonry-duration, .45s) var(--masonry-ease, cubic-bezier(.22, .61, .36, 1))}@media (prefers-reduced-motion: reduce){.masonry-container:not(.force-motion) .masonry-item[data-v-ce75570c],.masonry-container:not(.force-motion) .masonry-move[data-v-ce75570c]{transition-duration:1ms!important}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wyxos/vibe",
-  "version": "1.6.25",
+  "version": "1.6.27",
   "description": "A high-performance, responsive masonry layout engine for Vue 3 with built-in infinite scrolling and virtualization.",
   "keywords": [
     "vue",

package/src/Masonry.vue

@@ -9,7 +9,7 @@ import {
   getItemAttributes,
   calculateColumnHeights
 } from './masonryUtils'
-import { useMasonryTransitions } from './useMasonryTransitions'
+import { createMasonryTransitions } from './createMasonryTransitions'
 import { useMasonryScroll } from './useMasonryScroll'
 import { useSwipeMode as useSwipeModeComposable } from './useSwipeMode'
 import { useMasonryPagination } from './useMasonryPagination'
@@ -21,7 +21,7 @@ import MasonryItem from './components/MasonryItem.vue'
 import { normalizeError } from './utils/errorHandler'
 
 const props = defineProps({
-  getNextPage: {
+  getPage: {
     type: Function,
     default: () => { }
   },
@@ -33,6 +33,12 @@ const props = defineProps({
     type: Array,
     default: () => []
   },
+  // Opaque caller-owned context passed through to getPage(page, context).
+  // Useful for including filters, service selection, tabId, etc.
+  context: {
+    type: Object,
+    default: null
+  },
   layout: {
     type: Object
   },
@@ -41,27 +47,20 @@ const props = defineProps({
     default: 'page', // or 'cursor'
     validator: (v: string) => ['page', 'cursor'].includes(v)
   },
-  skipInitialLoad: {
-    type: Boolean,
-    default: false
-  },
-  // Initial pagination state when skipInitialLoad is true and items are provided
-  initialPage: {
-    type: [Number, String],
-    default: null
-  },
-  initialNextPage: {
-    type: [Number, String],
-    default: null
+  init: {
+    type: String,
+    default: 'manual',
+    validator: (v: string) => ['auto', 'manual'].includes(v)
   },
   pageSize: {
     type: Number,
     default: 40
   },
   // Backfill configuration
-  backfillEnabled: {
-    type: Boolean,
-    default: true
+  mode: {
+    type: String,
+    default: 'backfill',
+    validator: (value: string) => ['backfill', 'none', 'refresh'].includes(value)
   },
   backfillDelayMs: {
     type: Number,
@@ -110,10 +109,6 @@ const props = defineProps({
     type: Number,
     default: 200
   },
-  autoRefreshOnEmpty: {
-    type: Boolean,
-    default: false
-  },
   // Layout mode: 'auto' (detect from screen size), 'masonry', or 'swipe'
   layoutMode: {
     type: String,
@@ -181,19 +176,22 @@ const useSwipeMode = computed(() => {
 
 const emits = defineEmits([
   'update:items',
+  'loading:start',
   'backfill:start',
   'backfill:tick',
   'backfill:stop',
   'retry:start',
   'retry:tick',
   'retry:stop',
+  'loading:stop',
   'remove-all:complete',
   // Re-emit item-level preload events from the default MasonryItem
   'item:preload:success',
   'item:preload:error',
   // Mouse events from MasonryItem content
   'item:mouse-enter',
-  'item:mouse-leave'
+  'item:mouse-leave',
+  'update:context'
 ])
 
 const masonry = computed<any>({
@@ -201,6 +199,20 @@ const masonry = computed<any>({
   set: (val) => emits('update:items', val)
 })
 
+const context = computed<any>({
+  get: () => props.context,
+  set: (val) => emits('update:context', val)
+})
+
+function setContext(val: any) {
+  context.value = val
+}
+
+const masonryLength = computed((): number => {
+  const items = masonry.value as any[]
+  return items?.length ?? 0
+})
+
 const columns = ref<number>(7)
 const container = ref<HTMLElement | null>(null)
 const paginationHistory = ref<any[]>([])
@@ -209,6 +221,10 @@ const isLoading = ref<boolean>(false)
 const masonryContentHeight = ref<number>(0)
 const hasReachedEnd = ref<boolean>(false)  // Track when we've reached the last page
 const loadError = ref<Error | null>(null)  // Track load errors
+// Track when first content has loaded
+// For 'manual' init, show masonry immediately since we're about to load
+// For 'auto' init, wait for items to be provided or loaded
+const isInitialized = ref<boolean>(false)
 
 // Current breakpoint
 const currentBreakpoint = computed(() => getBreakpointName(containerWidth.value))
@@ -251,8 +267,8 @@ const virtualization = useMasonryVirtualization({
 // Extract virtualization state and functions
 const { viewportTop, viewportHeight, virtualizing, scrollProgress, visibleMasonry, updateScrollProgress, updateViewport: updateViewportVirtualization, reset: resetVirtualization } = virtualization
 
-// Initialize transitions composable with virtualization support
-const { onEnter, onBeforeEnter, onBeforeLeave, onLeave } = useMasonryTransitions(
+// Initialize transitions factory with virtualization support
+const { onEnter, onBeforeEnter, onBeforeLeave, onLeave } = createMasonryTransitions(
   { container, masonry: masonry as any },
   { leaveDurationMs: props.leaveDurationMs, virtualizing }
 )
@@ -265,7 +281,8 @@ const leave = onLeave
 
 // Initialize pagination composable
 const pagination = useMasonryPagination({
-  getNextPage: props.getNextPage as (page: any) => Promise<{ items: any[]; nextPage: any }>,
+  getPage: props.getPage as (page: any, ctx?: any) => Promise<{ items: any[]; nextPage: any }>,
+  context,
   masonry: masonry as any,
   isLoading,
   hasReachedEnd,
@@ -276,11 +293,10 @@ const pagination = useMasonryPagination({
   retryMaxAttempts: props.retryMaxAttempts,
   retryInitialDelayMs: props.retryInitialDelayMs,
   retryBackoffStepMs: props.retryBackoffStepMs,
-  backfillEnabled: props.backfillEnabled,
+  mode: props.mode,
   backfillDelayMs: props.backfillDelayMs,
   backfillMaxCalls: props.backfillMaxCalls,
   pageSize: props.pageSize,
-  autoRefreshOnEmpty: props.autoRefreshOnEmpty,
   emits
 })
 
@@ -324,12 +340,11 @@ const items = useMasonryItems({
   refreshCurrentPage,
   loadNext,
   maybeBackfillToTarget,
-  autoRefreshOnEmpty: props.autoRefreshOnEmpty,
   paginationHistory
 })
 
 // Extract item management functions
-const { remove, removeMany, restore, restoreMany, removeAll: removeAllItems } = items
+const { remove, removeMany, restore, restoreMany, removeAll } = items
 
 // setFixedDimensions is now in useMasonryLayout composable
 // Wrapper function to maintain API compatibility and handle wrapper restoration
@@ -343,39 +358,62 @@ function setFixedDimensions(dimensions: { width?: number; height?: number } | nu
 }
 
 defineExpose({
-  isLoading,
-  refreshLayout,
-  // Container dimensions (wrapper element)
-  containerWidth,
+  // Cancels any ongoing load operations (page loads, backfills, etc.)
+  cancelLoad,
+  // Opaque caller context passed through to getPage(page, context). Useful for including filters, service selection, tabId, etc.
+  context,
+  // Container height (wrapper element) in pixels
   containerHeight,
-  // Masonry content height (for backward compatibility, old containerHeight)
-  contentHeight: masonryContentHeight,
-  // Current page
+  // Container width (wrapper element) in pixels
+  containerWidth,
+  // Current Tailwind breakpoint name (base, sm, md, lg, xl, 2xl) based on containerWidth
+  currentBreakpoint,
+  // Current page number or cursor being displayed
   currentPage,
-  // End of list tracking
+  // Completely destroys the component, clearing all state and resetting to initial state
+  destroy,
+  // Boolean indicating if the end of the list has been reached (no more pages to load)
   hasReachedEnd,
-  // Load error tracking
+  // Initializes the component with items, page, and next page cursor. Use this for manual init mode.
+  initialize,
+  // Boolean indicating if the component has been initialized (first content has loaded)
+  isInitialized,
+  // Boolean indicating if a page load or backfill operation is currently in progress
+  isLoading,
+  // Error object if the last load operation failed, null otherwise
   loadError,
-  // Set fixed dimensions (overrides ResizeObserver)
-  setFixedDimensions,
-  remove,
-  removeMany,
-  removeAll: removeAllItems,
-  restore,
-  restoreMany,
+  // Loads the next page of items asynchronously
   loadNext,
+  // Loads a specific page number or cursor asynchronously
   loadPage,
+  // Array tracking pagination history (pages/cursors that have been loaded)
+  paginationHistory,
+  // Refreshes the current page by clearing items and reloading from the current page
   refreshCurrentPage,
+  // Recalculates the layout positions for all items. Call this after manually modifying items.
+  refreshLayout,
+  // Removes a single item from the masonry
+  remove,
+  // Removes all items from the masonry
+  removeAll,
+  // Removes multiple items from the masonry in a single operation
+  removeMany,
+  // Resets the component to initial state (clears items, resets pagination, scrolls to top)
   reset,
-  destroy,
-  init,
-  restoreItems,
-  paginationHistory,
-  cancelLoad,
-  scrollToTop,
+  // Restores a single item at its original index (useful for undo operations)
+  restore,
+  // Restores multiple items at their original indices (useful for undo operations)
+  restoreMany,
+  // Scrolls the container to a specific position
   scrollTo,
-  totalItems: computed(() => (masonry.value as any[]).length),
-  currentBreakpoint
+  // Scrolls the container to the top
+  scrollToTop,
+  // Sets the opaque caller context (alternative to v-model:context)
+  setContext,
+  // Sets fixed dimensions for the container, overriding ResizeObserver. Pass null to restore automatic sizing.
+  setFixedDimensions,
+  // Computed property returning the total number of items currently in the masonry
+  totalItems: computed(() => (masonry.value as any[]).length)
 })
 
 // Layout functions are now in useMasonryLayout composable
@@ -401,6 +439,18 @@ const goToNextItem = swipeMode.goToNextItem
 const goToPreviousItem = swipeMode.goToPreviousItem
 const snapToCurrentItem = swipeMode.snapToCurrentItem
 
+// Helper functions for swipe mode percentage calculations
+function getSwipeItemTop(index: string | number): string {
+  const length = masonryLength.value
+  const numIndex = typeof index === 'string' ? parseInt(index, 10) : index
+  return length > 0 ? `${numIndex * (100 / length)}%` : '0%'
+}
+
+function getSwipeItemHeight(): string {
+  const length = masonryLength.value
+  return length > 0 ? `${100 / length}%` : '0%'
+}
+
 // refreshCurrentPage is now in useMasonryPagination composable
 
 // Item management functions (remove, removeMany, restore, restoreMany, removeAll) are now in useMasonryItems composable
@@ -430,7 +480,7 @@ function scrollTo(options: { top?: number; left?: number; behavior?: ScrollBehav
   }
 }
 
-// removeAll is now in useMasonryItems composable (removeAllItems)
+// removeAll is now in useMasonryItems composable
 
 // onResize is now in useMasonryLayout composable (onResizeLayout)
 function onResize() {
@@ -461,12 +511,10 @@ function reset() {
   paginationHistory.value = [props.loadAtPage]
   hasReachedEnd.value = false  // Reset end flag
   loadError.value = null  // Reset error flag
+  isInitialized.value = false  // Reset initialization flag
 
   // Reset virtualization state
   resetVirtualization()
-
-  // Reset auto-initialization flag so watcher can work again if needed
-  hasInitializedWithItems = false
 }
 
 function destroy() {
@@ -481,6 +529,7 @@ function destroy() {
   hasReachedEnd.value = false
   loadError.value = null
   isLoading.value = false
+  isInitialized.value = false
 
   // Reset swipe mode state
   currentSwipeIndex.value = 0
@@ -519,24 +568,32 @@ function handleWindowResize() {
   // Note: containerWidth is updated by ResizeObserver
 }
 
-function init(items: any[], page: any, next: any) {
+function initialize(items: any[], page: any, next: any) {
   currentPage.value = page  // Track the initial current page
   paginationHistory.value = [page]
-  paginationHistory.value.push(next)
-  // Update hasReachedEnd if next is null
-  hasReachedEnd.value = next == null
+  if (next !== null && next !== undefined) {
+    paginationHistory.value.push(next)
+  }
+  // Only treat explicit null as end-of-list. Undefined means "unknown".
+  hasReachedEnd.value = next === null
   // Diagnostics: check incoming initial items
-  checkItemDimensions(items as any[], 'init')
+  checkItemDimensions(items as any[], 'initialize')
+
+  // If masonry is empty, replace items; otherwise add them
+  const currentItems = masonry.value as any[]
+  const newItems = currentItems.length === 0 ? items : [...currentItems, ...items]
+
+  // Set items first (this updates the v-model)
+  masonry.value = newItems
 
   if (useSwipeMode.value) {
-    // In swipe mode, just add items without layout calculation
-    masonry.value = [...(masonry.value as any[]), ...items]
+    // In swipe mode, just set items without layout calculation
     // Reset swipe index if we're at the start
     if (currentSwipeIndex.value === 0 && masonry.value.length > 0) {
       swipeOffset.value = 0
     }
   } else {
-    refreshLayout([...(masonry.value as any[]), ...items])
+    refreshLayout(newItems)
 
     // Update viewport state from container's scroll position
     // Critical after refresh when browser may restore scroll position
@@ -555,89 +612,14 @@ function init(items: any[], page: any, next: any) {
       }
     })
   }
-}
-
-/**
- * Restore items when skipInitialLoad is true.
- * This method should be called instead of directly assigning to v-model:items
- * when restoring items from saved state.
- * @param items - Items to restore
- * @param page - Current page number/cursor
- * @param next - Next page cursor (or null if at end)
- */
-async function restoreItems(items: any[], page: any, next: any) {
-  // If skipInitialLoad is false, fall back to init behavior
-  if (!props.skipInitialLoad) {
-    init(items, page, next)
-    return
-  }
-
-  // When skipInitialLoad is true, we need to restore items without triggering initial load
-  currentPage.value = page
-  paginationHistory.value = [page]
-  if (next !== null && next !== undefined) {
-    paginationHistory.value.push(next)
-  }
-  // Only set hasReachedEnd to true if next is explicitly null (end of list)
-  // undefined means "unknown" - don't assume end of list
-  hasReachedEnd.value = next === null
-  loadError.value = null
-
-  // Diagnostics: check incoming items
-  checkItemDimensions(items as any[], 'restoreItems')
-
-  // Set items directly (v-model will sync) and refresh layout
-  // Follow the same pattern as init() and getContent()
-  if (useSwipeMode.value) {
-    // In swipe mode, just set items without layout calculation
-    masonry.value = items
-    // Reset swipe index if we're at the start
-    if (currentSwipeIndex.value === 0 && masonry.value.length > 0) {
-      swipeOffset.value = 0
-    }
-  } else {
-    // In masonry mode, refresh layout with the restored items
-    refreshLayout(items)
-
-    // Update viewport state from container's scroll position
-    if (container.value) {
-      viewportTop.value = container.value.scrollTop
-      viewportHeight.value = container.value.clientHeight || window.innerHeight
-    }
 
-    // Update again after DOM updates to catch browser scroll restoration
-    await nextTick()
-    if (container.value) {
-      viewportTop.value = container.value.scrollTop
-      viewportHeight.value = container.value.clientHeight || window.innerHeight
-      updateScrollProgress()
-      
-      // Check if user is already at the bottom after restoration
-      // If so, trigger loading to restore scroll-to-bottom functionality
-      // Wait for layout to be fully calculated before checking
-      await nextTick()
-      const columnHeights = calculateColumnHeights(masonry.value as any, columns.value)
-      const tallest = columnHeights.length ? Math.max(...columnHeights) : 0
-      const scrollerBottom = container.value.scrollTop + container.value.clientHeight
-      const threshold = typeof props.loadThresholdPx === 'number' ? props.loadThresholdPx : 200
-      const triggerPoint = threshold >= 0
-        ? Math.max(0, tallest - threshold)
-        : Math.max(0, tallest + threshold)
-      const nearBottom = scrollerBottom >= triggerPoint
-      
-      // If user is at bottom and there's a next page, trigger loading
-      // This restores scroll-to-bottom functionality after tab restoration
-      if (nearBottom && !hasReachedEnd.value && !isLoading.value && paginationHistory.value.length > 0) {
-        const nextPage = paginationHistory.value[paginationHistory.value.length - 1]
-        if (nextPage != null) {
-          // Use handleScroll with forceCheck=true to bypass isScrollingDown check
-          await handleScroll(columnHeights, true)
-        }
-      }
-    }
+  // Mark as initialized when items are provided
+  if (items && items.length > 0) {
+    isInitialized.value = true
   }
 }
 
+
 // Watch for layout changes and update columns + refresh layout dynamically
 watch(
   layout,
@@ -676,31 +658,14 @@ watch(container, (el) => {
   }
 }, { immediate: true })
 
-// Watch for items when skipInitialLoad is true to auto-initialize pagination state
-// This handles cases where items are provided after mount or updated externally
-let hasInitializedWithItems = false
+// Watch for when items are first loaded (for init='manual' when items are loaded via initialize)
 watch(
-  () => [props.items, props.skipInitialLoad, props.initialPage, props.initialNextPage] as const,
-  ([items, skipInitialLoad, initialPage, initialNextPage]) => {
-    // Only auto-initialize if:
-    // 1. skipInitialLoad is true
-    // 2. Items exist
-    // 3. We haven't already initialized with items (to avoid re-initializing on every update)
-    if (
-      skipInitialLoad &&
-      items &&
-      items.length > 0 &&
-      !hasInitializedWithItems
-    ) {
-      hasInitializedWithItems = true
-      const page = initialPage !== null && initialPage !== undefined
-        ? initialPage
-        : (props.loadAtPage as any)
-      const next = initialNextPage !== undefined
-        ? initialNextPage
-        : undefined // undefined means "unknown", null means "end of list"
-
-      restoreItems(items as any[], page, next)
+  () => masonry.value.length,
+  (newLength, oldLength) => {
+    // For manual mode, mark as initialized when items first appear
+    // This handles the case where items are loaded via initialize after mount
+    if (props.init === 'manual' && !isInitialized.value && newLength > 0 && oldLength === 0) {
+      isInitialized.value = true
     }
   },
   { immediate: false }
@@ -852,23 +817,21 @@ onMounted(async () => {
     const initialPage = props.loadAtPage as any
     paginationHistory.value = [initialPage]
 
-    if (!props.skipInitialLoad) {
-      await loadPage(paginationHistory.value[0] as any)
-    } else if (props.items && props.items.length > 0) {
-      // When skipInitialLoad is true and items are provided, initialize pagination state
-      // Use initialPage/initialNextPage props if provided, otherwise use loadAtPage
-      // Only set next to null if initialNextPage is explicitly null (not undefined)
-      const page = props.initialPage !== null && props.initialPage !== undefined
-        ? props.initialPage
-        : (props.loadAtPage as any)
-      const next = props.initialNextPage !== undefined
-        ? props.initialNextPage
-        : undefined // undefined means "unknown", null means "end of list"
-
-      await restoreItems(props.items as any[], page, next)
-      // Mark as initialized to prevent watcher from running again
-      hasInitializedWithItems = true
+    if (props.init === 'auto') {
+      // Auto mode: automatically call loadPage on mount
+      // Set initialized BEFORE loading so the masonry container renders
+      // This allows refreshLayout to access the container element for measurements
+      isInitialized.value = true
+      await nextTick() // Ensure container is rendered before loading
+
+      try {
+        await loadPage(initialPage)
+      } catch (error) {
+        // Error is already handled by loadPage via loadError
+        // Continue - component is already initialized
+      }
     }
+    // Manual mode: do nothing, user will manually call restore()
 
     if (!useSwipeMode.value) {
       updateScrollProgress()
@@ -886,6 +849,7 @@ onMounted(async () => {
       loadError.value = normalizeError(error)
     }
     isLoading.value = false
+    // isInitialized is already set to true before loadPage for 'auto' mode
   }
 
   // Scroll listener is handled by watcher now for consistency
@@ -918,19 +882,26 @@ onUnmounted(() => {
 
 <template>
   <div ref="wrapper" class="w-full h-full flex flex-col relative">
+    <!-- Loading message while waiting for initial content -->
+    <div v-if="!isInitialized" class="w-full h-full flex items-center justify-center">
+      <slot name="loading-message">
+        <p class="text-gray-500 dark:text-gray-400">Waiting for content to load...</p>
+      </slot>
+    </div>
+
     <!-- Swipe Feed Mode (Mobile/Tablet) -->
-    <div v-if="useSwipeMode" class="overflow-hidden w-full flex-1 swipe-container touch-none select-none"
+    <div v-else-if="useSwipeMode" class="overflow-hidden w-full flex-1 swipe-container touch-none select-none"
       :class="{ 'force-motion': props.forceMotion, 'cursor-grab': !isDragging, 'cursor-grabbing': isDragging }"
       ref="swipeContainer" style="height: 100%; max-height: 100%; position: relative;">
       <div class="relative w-full" :style="{
         transform: `translateY(${swipeOffset}px)`,
         transition: isDragging ? 'none' : `transform ${transitionDurationMs}ms ${transitionEasing}`,
-        height: `${masonry.length * 100}%`
+        height: `${masonryLength * 100}%`
       }">
         <div v-for="(item, index) in masonry" :key="`${item.page}-${item.id}`" class="absolute top-0 left-0 w-full"
           :style="{
-            top: `${index * (100 / masonry.length)}%`,
-            height: `${100 / masonry.length}%`
+            top: getSwipeItemTop(index),
+            height: getSwipeItemHeight()
           }">
           <div class="w-full h-full flex items-center justify-center p-4">
             <div class="w-full h-full max-w-full max-h-full relative">