@wyxos/vibe 1.4.1 → 1.5.0

package/lib/vibe.css

@@ -1 +1 @@
-.masonry-container[data-v-a75cd886]{overflow-anchor:none}.masonry-item[data-v-a75cd886]{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-a75cd886]{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-a75cd886],.masonry-container:not(.force-motion) .masonry-move[data-v-a75cd886]{transition-duration:1ms!important}}
+.masonry-container[data-v-b855ca99]{overflow-anchor:none}.masonry-item[data-v-b855ca99]{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-b855ca99]{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-b855ca99],.masonry-container:not(.force-motion) .masonry-move[data-v-b855ca99]{transition-duration:1ms!important}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wyxos/vibe",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "main": "lib/index.js",
   "module": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -42,9 +42,10 @@
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.0.15",
+    "@types/lodash-es": "^4.17.12",
+    "@types/node": "^24.5.2",
     "@vitejs/plugin-vue": "^5.2.1",
     "@vue/test-utils": "^2.4.6",
-    "@types/node": "^24.5.2",
     "chalk": "^5.3.0",
     "inquirer": "^10.1.8",
     "jsdom": "^26.0.0",

package/src/App.vue

@@ -8,6 +8,8 @@ const items = ref<MasonryItem[]>([]);
 
 const masonry = ref<InstanceType<typeof Masonry> | null>(null);
 
+const layout = { sizes: { base: 1, sm: 2, md: 3, lg: 4, xl: 5, '2xl': 10 }, header: 40, footer: 40 };
+
 const getPage = async (page: number): Promise<GetPageResult> => {
   return new Promise((resolve) => {
     setTimeout(() => {
@@ -49,7 +51,7 @@ const getPage = async (page: number): Promise<GetPageResult> => {
         <p>Showing: <span class="bg-blue-500 text-white p-2 rounded">{{ items.length }}</span></p>
       </div>
     </header>
-    <masonry class="bg-blue-500 " v-model:items="items" :get-next-page="getPage" :load-at-page="1" ref="masonry">
+    <masonry class="bg-blue-500 " v-model:items="items" :get-next-page="getPage" :load-at-page="1" :layout="layout" ref="masonry">
       <template #item="{item, remove}">
         <img :src="item.src" class="w-full"/>
         <button class="absolute bottom-0 right-0 bg-red-500 text-white p-2 rounded cursor-pointer" @click="remove(item)">

package/src/Masonry.vue

@@ -36,10 +36,6 @@ const props = defineProps({
     type: Boolean,
     default: false
   },
-  maxItems: {
-    type: Number,
-    default: 100
-  },
   pageSize: {
     type: Number,
     default: 40
@@ -87,6 +83,14 @@ const props = defineProps({
   forceMotion: {
     type: Boolean,
     default: false
+  },
+  virtualBufferPx: {
+    type: Number,
+    default: 600
+  },
+  loadThresholdPx: {
+    type: Number,
+    default: 200
   }
 })
 
@@ -117,7 +121,8 @@ const emits = defineEmits([
   'backfill:stop',
   'retry:start',
   'retry:tick',
-  'retry:stop'
+  'retry:stop',
+  'remove-all:complete'
 ])
 
 const masonry = computed<any>({
@@ -128,25 +133,72 @@ const masonry = computed<any>({
 const columns = ref<number>(7)
 const container = ref<HTMLElement | null>(null)
 const paginationHistory = ref<any[]>([])
-const nextPage = ref<number | null>(null)
 const isLoading = ref<boolean>(false)
 const containerHeight = ref<number>(0)
 
+// Diagnostics: track items missing width/height to help developers
+const invalidDimensionIds = ref<Set<number | string>>(new Set())
+function isPositiveNumber(value: unknown): boolean {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0
+}
+function checkItemDimensions(items: any[], context: string) {
+  try {
+    if (!Array.isArray(items) || items.length === 0) return
+    const missing = items.filter((item) => !isPositiveNumber(item?.width) || !isPositiveNumber(item?.height))
+    if (missing.length === 0) return
+
+    const newIds: Array<number | string> = []
+    for (const item of missing) {
+      const id = (item?.id as number | string | undefined) ?? `idx:${items.indexOf(item)}`
+      if (!invalidDimensionIds.value.has(id)) {
+        invalidDimensionIds.value.add(id)
+        newIds.push(id)
+      }
+    }
+    if (newIds.length > 0) {
+      const sample = newIds.slice(0, 10)
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[Masonry] Items missing width/height detected:',
+        {
+          context,
+          count: newIds.length,
+          sampleIds: sample,
+          hint: 'Ensure each item has positive width and height. Consider providing fallbacks (e.g., 512x512) at the data layer.'
+        }
+      )
+    }
+  } catch {
+    // best-effort diagnostics only
+  }
+}
+
+// Virtualization viewport state
+const viewportTop = ref(0)
+const viewportHeight = ref(0)
+const VIRTUAL_BUFFER_PX = props.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
 })
 
-const updateScrollProgress = () => {
+const updateScrollProgress = (precomputedHeights?: number[]) => {
   if (!container.value) return
 
   const {scrollTop, clientHeight} = container.value
   const visibleBottom = scrollTop + clientHeight
 
-  const columnHeights = calculateColumnHeights(masonry.value as any, columns.value)
-  const longestColumn = Math.max(...columnHeights)
-  const triggerPoint = longestColumn + 300
+  const columnHeights = precomputedHeights ?? calculateColumnHeights(masonry.value as any, columns.value)
+  const tallest = columnHeights.length ? Math.max(...columnHeights) : 0
+  const threshold = typeof props.loadThresholdPx === 'number' ? props.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
@@ -158,7 +210,65 @@ const updateScrollProgress = () => {
 }
 
 // Setup composables
-const {onEnter, onBeforeEnter, onBeforeLeave, onLeave} = useMasonryTransitions(masonry)
+const {onEnter, onBeforeEnter, onBeforeLeave, onLeave} = useMasonryTransitions(masonry, { leaveDurationMs: props.leaveDurationMs })
+
+// Transition wrappers that skip animation during virtualization
+function enter(el: HTMLElement, done: () => void) {
+  if (virtualizing.value) {
+    const left = parseInt(el.dataset.left || '0', 10)
+    const top = parseInt(el.dataset.top || '0', 10)
+    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()
+    })
+  } else {
+    onEnter(el, done)
+  }
+}
+function beforeEnter(el: HTMLElement) {
+  if (virtualizing.value) {
+    const left = parseInt(el.dataset.left || '0', 10)
+    const top = parseInt(el.dataset.top || '0', 10)
+    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')
+  } else {
+    onBeforeEnter(el)
+  }
+}
+function beforeLeave(el: HTMLElement) {
+  if (virtualizing.value) {
+    // no-op; removal will be immediate in leave
+  } else {
+    onBeforeLeave(el)
+  }
+}
+function leave(el: HTMLElement, done: () => void) {
+  if (virtualizing.value) {
+    // Skip animation during virtualization
+    done()
+  } else {
+    onLeave(el, done)
+  }
+}
+
+// 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[]
+  return items.filter((it: any) => {
+    const itemTop = it.top
+    const itemBottom = it.top + it.columnHeight
+    return itemBottom >= top && itemTop <= bottom
+  })
+})
 
 const {handleScroll} = useMasonryScroll({
   container,
@@ -166,14 +276,13 @@ const {handleScroll} = useMasonryScroll({
   columns,
   containerHeight,
   isLoading,
-  maxItems: props.maxItems,
   pageSize: props.pageSize,
   refreshLayout,
   setItemsRaw: (items: any[]) => {
     masonry.value = items
   },
   loadNext,
-  leaveEstimateMs: props.leaveDurationMs
+  loadThresholdPx: props.loadThresholdPx
 })
 
 defineExpose({
@@ -182,11 +291,15 @@ defineExpose({
   containerHeight,
   remove,
   removeMany,
+  removeAll,
   loadNext,
   loadPage,
   reset,
   init,
-  paginationHistory
+  paginationHistory,
+  cancelLoad,
+  scrollToTop,
+  totalItems: computed(() => (masonry.value as any[]).length)
 })
 
 function calculateHeight(content: any[]) {
@@ -201,6 +314,8 @@ function calculateHeight(content: any[]) {
 
 function refreshLayout(items: any[]) {
   if (!container.value) return
+  // Developer diagnostics: warn when dimensions are invalid
+  checkItemDimensions(items as any[], 'refreshLayout')
   const content = calculateLayout(items as any, container.value as HTMLElement, columns.value, layout.value as any)
   calculateHeight(content as any)
   masonry.value = content
@@ -212,6 +327,12 @@ function waitWithProgress(totalMs: number, onTick: (remaining: number, total: nu
     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)
@@ -262,11 +383,14 @@ async function fetchWithRetry<T = any>(fn: () => Promise<T>): Promise<T> {
 }
 
 async function loadPage(page: number) {
-  if (isLoading.value) return
+  if (isLoading.value || cancelRequested.value) return
   isLoading.value = true
+  cancelRequested.value = false
   try {
     const baseline = (masonry.value as any[]).length
+    if (cancelRequested.value) return
     const response = await getContent(page)
+    if (cancelRequested.value) return
     paginationHistory.value.push(response.nextPage)
     await maybeBackfillToTarget(baseline)
     return response
@@ -279,12 +403,15 @@ async function loadPage(page: number) {
 }
 
 async function loadNext() {
-  if (isLoading.value) return
+  if (isLoading.value || cancelRequested.value) return
   isLoading.value = true
+  cancelRequested.value = false
   try {
     const baseline = (masonry.value as any[]).length
+    if (cancelRequested.value) return
     const currentPage = paginationHistory.value[paginationHistory.value.length - 1]
     const response = await getContent(currentPage)
+    if (cancelRequested.value) return
     paginationHistory.value.push(response.nextPage)
     await maybeBackfillToTarget(baseline)
     return response
@@ -300,9 +427,9 @@ async function remove(item: any) {
   const next = (masonry.value as any[]).filter(i => i.id !== item.id)
   masonry.value = next
   await nextTick()
-  // Force a reflow so current transforms are committed
-  void container.value?.offsetHeight
-  // Start FLIP on next frame (single RAF)
+  // Commit DOM updates without forcing sync reflow
+  await new Promise<void>(r => requestAnimationFrame(() => r()))
+  // Start FLIP on next frame
   requestAnimationFrame(() => {
     refreshLayout(next)
   })
@@ -314,24 +441,56 @@ async function removeMany(items: any[]) {
   const next = (masonry.value as any[]).filter(i => !ids.has(i.id))
   masonry.value = next
   await nextTick()
-  // Force a reflow so survivors' current transforms are committed
-  void container.value?.offsetHeight
-  // Start FLIP on next frame (single RAF)
+  // Commit DOM updates without forcing sync reflow
+  await new Promise<void>(r => requestAnimationFrame(() => r()))
+  // Start FLIP on next frame
   requestAnimationFrame(() => {
     refreshLayout(next)
   })
 }
 
+function scrollToTop(options?: ScrollToOptions) {
+  if (container.value) {
+    container.value.scrollTo({
+      top: 0,
+      behavior: options?.behavior ?? 'smooth',
+      ...options
+    })
+  }
+}
+
+async function removeAll() {
+  // Scroll to top first for better UX
+  scrollToTop({ behavior: 'smooth' })
+  
+  // Clear all items
+  masonry.value = []
+  
+  // Recalculate height to 0
+  containerHeight.value = 0
+  
+  await nextTick()
+  
+  // Emit completion event
+  emits('remove-all:complete')
+}
+
 function onResize() {
   columns.value = getColumnCount(layout.value as any)
   refreshLayout(masonry.value as any)
+  if (container.value) {
+    viewportTop.value = container.value.scrollTop
+    viewportHeight.value = container.value.clientHeight
+  }
 }
 
 let backfillActive = false
+const cancelRequested = ref(false)
 
 async function maybeBackfillToTarget(baselineCount: number) {
   if (!props.backfillEnabled) return
   if (backfillActive) return
+  if (cancelRequested.value) return
 
   const targetCount = (baselineCount || 0) + (props.pageSize || 0)
   if (!props.pageSize || props.pageSize <= 0) return
@@ -349,7 +508,8 @@ async function maybeBackfillToTarget(baselineCount: number) {
     while (
       (masonry.value as any[]).length < targetCount &&
       calls < props.backfillMaxCalls &&
-      paginationHistory.value[paginationHistory.value.length - 1] != null
+      paginationHistory.value[paginationHistory.value.length - 1] != null &&
+      !cancelRequested.value
     ) {
       await waitWithProgress(props.backfillDelayMs, (remaining, total) => {
         emits('backfill:tick', {
@@ -361,10 +521,13 @@ async function maybeBackfillToTarget(baselineCount: number) {
         })
       })
 
+      if (cancelRequested.value) break
+
       const currentPage = paginationHistory.value[paginationHistory.value.length - 1]
       try {
         isLoading.value = true
         const response = await getContent(currentPage)
+        if (cancelRequested.value) break
         paginationHistory.value.push(response.nextPage)
       } finally {
         isLoading.value = false
@@ -379,7 +542,14 @@ async function maybeBackfillToTarget(baselineCount: number) {
   }
 }
 
+function cancelLoad() {
+  cancelRequested.value = true
+  isLoading.value = false
+  backfillActive = false
+}
+
 function reset() {
+  cancelLoad()
   if (container.value) {
     container.value.scrollTo({
       top: 0,
@@ -397,9 +567,20 @@ function reset() {
   }
 }
 
-const debouncedScrollHandler = debounce(() => {
-  handleScroll()
-  updateScrollProgress()
+const debouncedScrollHandler = debounce(async () => {
+  if (container.value) {
+    viewportTop.value = container.value.scrollTop
+    viewportHeight.value = container.value.clientHeight
+  }
+  // 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)
+  handleScroll(heights as any)
+  updateScrollProgress(heights)
 }, 200)
 
 const debouncedResizeHandler = debounce(onResize, 200)
@@ -407,6 +588,8 @@ const debouncedResizeHandler = debounce(onResize, 200)
 function init(items: any[], page: any, next: any) {
   paginationHistory.value = [page]
   paginationHistory.value.push(next)
+  // Diagnostics: check incoming initial items
+  checkItemDimensions(items as any[], 'init')
   refreshLayout([...(masonry.value as any[]), ...items])
   updateScrollProgress()
 }
@@ -414,6 +597,10 @@ function init(items: any[], page: any, next: any) {
 onMounted(async () => {
   try {
     columns.value = getColumnCount(layout.value as any)
+    if (container.value) {
+      viewportTop.value = container.value.scrollTop
+      viewportHeight.value = container.value.clientHeight
+    }
 
     const initialPage = props.loadAtPage as any
     paginationHistory.value = [initialPage]
@@ -429,7 +616,7 @@ onMounted(async () => {
     isLoading.value = false
   }
 
-  container.value?.addEventListener('scroll', debouncedScrollHandler)
+  container.value?.addEventListener('scroll', debouncedScrollHandler, { passive: true })
   window.addEventListener('resize', debouncedResizeHandler)
 })
 
@@ -443,14 +630,14 @@ onUnmounted(() => {
   <div class="overflow-auto w-full flex-1 masonry-container" :class="{ 'force-motion': props.forceMotion }" ref="container">
     <div class="relative"
          :style="{height: `${containerHeight}px`, '--masonry-duration': `${transitionDurationMs}ms`, '--masonry-leave-duration': `${leaveDurationMs}ms`, '--masonry-ease': transitionEasing}">
-      <transition-group name="masonry" :css="false" @enter="onEnter" @before-enter="onBeforeEnter"
-                        @leave="onLeave"
-                        @before-leave="onBeforeLeave">
-        <div v-for="(item, i) in masonry" :key="`${item.page}-${item.id}`"
+      <transition-group name="masonry" :css="false" @enter="enter" @before-enter="beforeEnter"
+                        @leave="leave"
+                        @before-leave="beforeLeave">
+        <div v-for="(item, i) in visibleMasonry" :key="`${item.page}-${item.id}`"
              class="absolute masonry-item"
              v-bind="getItemAttributes(item, i)">
           <slot name="item" v-bind="{item, remove}">
-            <img :src="item.src" class="w-full"/>
+            <img :src="item.src" class="w-full" loading="lazy" decoding="async"/>
             <button class="absolute bottom-0 right-0 bg-red-500 text-white p-2 rounded cursor-pointer"
                     @click="remove(item)">
               <i class="fas fa-trash"></i>