vue-virtual-flow 0.0.3 → 0.0.4

package/README.md

@@ -4,7 +4,7 @@
 
 A small, typed, and accessible collection of virtual scrolling components for
 Vue 3. It covers fixed and variable-height lists, window scrolling, chat,
-short-media feeds, and horizontal carousels.
+window-scrolling grids, short-media feeds, and horizontal carousels.
 
 Only the items needed for the current viewport are mounted, keeping large data
 sets responsive without prescribing how an item should look.
@@ -18,6 +18,7 @@ sets responsive without prescribing how an item should look.
   - [VirtualList and DynamicVirtualScroll](#virtuallist-and-dynamicvirtualscroll)
   - [VirtualScroll](#virtualscroll)
   - [WindowDynamicVirtualScroll](#windowdynamicvirtualscroll)
+  - [WindowGirdVirtualScroll](#windowgirdvirtualscroll)
   - [ChatVirtualScroll](#chatvirtualscroll)
   - [ShortMediaFeed](#shortmediafeed)
   - [VirtualCarousel](#virtualcarousel)
@@ -83,8 +84,8 @@ createApp(App).use(VueVirtualScroll).mount('#app')
 ```
 
 The plugin registers `VirtualList`, `DynamicVirtualScroll`, `VirtualScroll`,
-`WindowDynamicVirtualScroll`, `ChatVirtualScroll`, `ShortMediaFeed`, and
-`VirtualCarousel`.
+`WindowDynamicVirtualScroll`, `WindowGirdVirtualScroll`, `ChatVirtualScroll`,
+`ShortMediaFeed`, and `VirtualCarousel`.
 
 ## Choose a component
 
@@ -94,6 +95,7 @@ The plugin registers `VirtualList`, `DynamicVirtualScroll`, `VirtualScroll`,
 | `DynamicVirtualScroll` | Same behavior as `VirtualList`, with an explicit name. | Component container | Variable, measured automatically |
 | `VirtualScroll` | Every row has the same known height. | Component container | Fixed |
 | `WindowDynamicVirtualScroll` | The page itself should scroll instead of a nested container. | Browser window | Variable, measured automatically |
+| `WindowGirdVirtualScroll` | A fixed-height card grid should use page scrolling. | Browser window | Fixed row height |
 | `ChatVirtualScroll` | Messages are appended at the bottom and older history is prepended. | Component container | Variable, measured automatically |
 | `ShortMediaFeed` | One full-height item should snap into view at a time. | Component container | One viewport per item |
 | `VirtualCarousel` | Several horizontal slides should snap and virtualize. | Component container | Calculated from container width |
@@ -362,6 +364,47 @@ const list = ref<VirtualScrollExpose>()
 - Methods: `scrollTo`, `scrollToIndex`, and `scrollToTop`. They scroll the
   browser window; `scrollTo` accepts an offset relative to the list.
 
+### WindowGirdVirtualScroll
+
+Use `WindowGirdVirtualScroll` for a multi-column grid whose cards have a known,
+fixed height and whose viewport is the browser window. Virtualization happens
+by complete rows, so every visible column remains mounted together.
+
+```vue
+<script setup lang="ts">
+import { WindowGirdVirtualScroll } from 'vue-virtual-flow'
+
+const products = Array.from({ length: 10_000 }, (_, id) => ({
+  id,
+  name: `Product ${id + 1}`,
+}))
+</script>
+
+<template>
+  <WindowGirdVirtualScroll
+    :items="products"
+    :item-size="240"
+    :columns="4"
+    :gap="16"
+    item-key="id"
+    aria-label="Product grid"
+  >
+    <template #default="{ item, rowIndex, columnIndex }">
+      <ProductCard
+        :product="item"
+        :data-position="`${rowIndex}:${columnIndex}`"
+      />
+    </template>
+  </WindowGirdVirtualScroll>
+</template>
+```
+
+`itemSize` is the height of one grid row. Content that exceeds it is clipped.
+`columns` defaults to `2`, `gap` defaults to `0`, and `overscan` defaults to
+one extra row before and after the visible range. The remaining list props,
+events, named slots, and exposed methods match `WindowDynamicVirtualScroll`.
+The default slot also receives `rowIndex` and `columnIndex`.
+
 ### ChatVirtualScroll
 
 `ChatVirtualScroll` is designed for variable-height conversations. It opens at
@@ -719,7 +762,8 @@ converted to pixels. `height="fill"` is shorthand for `height="100%"`:
 
 A percentage height only works when its parent has an explicit height.
 Development builds warn when it resolves to `0px`.
-`WindowDynamicVirtualScroll` uses the browser window and has no `height` prop.
+`WindowDynamicVirtualScroll` and `WindowGirdVirtualScroll` use the browser
+window and have no `height` prop.
 
 ### Stable item keys
 
@@ -782,7 +826,8 @@ to false after the final page.
 ### Pull to refresh
 
 Pull-to-refresh is available on `VirtualList`, `DynamicVirtualScroll`,
-`VirtualScroll`, and `WindowDynamicVirtualScroll`:
+`VirtualScroll`, `WindowDynamicVirtualScroll`, and
+`WindowGirdVirtualScroll`:
 
 ```vue
 <VirtualList
@@ -823,6 +868,7 @@ import type {
   VirtualScrollExpose,
   VirtualScrollProps,
   WindowDynamicVirtualScrollProps,
+  WindowGirdVirtualScrollProps,
 } from 'vue-virtual-flow'
 ```
 

package/README.vi.md

@@ -4,7 +4,7 @@
 
 Bộ component virtual scrolling nhỏ gọn, có type đầy đủ và hỗ trợ khả năng tiếp
 cận cho Vue 3. Thư viện hỗ trợ danh sách chiều cao cố định hoặc động, cuộn theo
-cửa sổ, giao diện chat, feed media ngắn và carousel ngang.
+cửa sổ, grid cuộn theo cửa sổ, giao diện chat, feed media ngắn và carousel ngang.
 
 Chỉ các item cần thiết cho viewport hiện tại được mount, nhờ đó tập dữ liệu lớn
 vẫn phản hồi nhanh mà component không áp đặt giao diện của từng item.
@@ -18,6 +18,7 @@ vẫn phản hồi nhanh mà component không áp đặt giao diện của từn
   - [VirtualList và DynamicVirtualScroll](#virtuallist-và-dynamicvirtualscroll)
   - [VirtualScroll](#virtualscroll)
   - [WindowDynamicVirtualScroll](#windowdynamicvirtualscroll)
+  - [WindowGirdVirtualScroll](#windowgirdvirtualscroll)
   - [ChatVirtualScroll](#chatvirtualscroll)
   - [ShortMediaFeed](#shortmediafeed)
   - [VirtualCarousel](#virtualcarousel)
@@ -83,8 +84,8 @@ createApp(App).use(VueVirtualScroll).mount('#app')
 ```
 
 Plugin đăng ký `VirtualList`, `DynamicVirtualScroll`, `VirtualScroll`,
-`WindowDynamicVirtualScroll`, `ChatVirtualScroll`, `ShortMediaFeed` và
-`VirtualCarousel`.
+`WindowDynamicVirtualScroll`, `WindowGirdVirtualScroll`, `ChatVirtualScroll`,
+`ShortMediaFeed` và `VirtualCarousel`.
 
 ## Chọn component
 
@@ -94,6 +95,7 @@ Plugin đăng ký `VirtualList`, `DynamicVirtualScroll`, `VirtualScroll`,
 | `DynamicVirtualScroll` | Giống `VirtualList` nhưng tên gọi thể hiện rõ chiều cao động. | Container của component | Động, tự đo |
 | `VirtualScroll` | Tất cả hàng có cùng chiều cao đã biết. | Container của component | Cố định |
 | `WindowDynamicVirtualScroll` | Muốn trang cuộn thay vì tạo một container cuộn lồng bên trong. | Cửa sổ trình duyệt | Động, tự đo |
+| `WindowGirdVirtualScroll` | Grid card có chiều cao cố định và dùng trang để cuộn. | Cửa sổ trình duyệt | Chiều cao hàng cố định |
 | `ChatVirtualScroll` | Tin nhắn mới được thêm ở cuối và lịch sử cũ được thêm ở đầu. | Container của component | Động, tự đo |
 | `ShortMediaFeed` | Mỗi lần cần snap một item đầy viewport. | Container của component | Một viewport cho mỗi item |
 | `VirtualCarousel` | Cần hiển thị và snap nhiều slide theo chiều ngang. | Container của component | Tính từ chiều rộng container |
@@ -362,6 +364,47 @@ const list = ref<VirtualScrollExpose>()
 - Methods: `scrollTo`, `scrollToIndex` và `scrollToTop`. Các method này cuộn
   cửa sổ trình duyệt; `scrollTo` nhận offset tương đối so với đầu danh sách.
 
+### WindowGirdVirtualScroll
+
+Dùng `WindowGirdVirtualScroll` cho grid nhiều cột có card với chiều cao cố định
+đã biết và dùng cửa sổ trình duyệt làm viewport. Component virtualize theo cả
+hàng để các cột đang hiển thị luôn được mount cùng nhau.
+
+```vue
+<script setup lang="ts">
+import { WindowGirdVirtualScroll } from 'vue-virtual-flow'
+
+const products = Array.from({ length: 10_000 }, (_, id) => ({
+  id,
+  name: `Sản phẩm ${id + 1}`,
+}))
+</script>
+
+<template>
+  <WindowGirdVirtualScroll
+    :items="products"
+    :item-size="240"
+    :columns="4"
+    :gap="16"
+    item-key="id"
+    aria-label="Grid sản phẩm"
+  >
+    <template #default="{ item, rowIndex, columnIndex }">
+      <ProductCard
+        :product="item"
+        :data-position="`${rowIndex}:${columnIndex}`"
+      />
+    </template>
+  </WindowGirdVirtualScroll>
+</template>
+```
+
+`itemSize` là chiều cao của một hàng grid; nội dung vượt quá kích thước này sẽ
+bị ẩn. `columns` mặc định là `2`, `gap` mặc định là `0`, còn `overscan` mặc
+định render thêm một hàng trước và sau vùng nhìn thấy. Các prop list còn lại,
+event, named slot và method qua ref giống `WindowDynamicVirtualScroll`. Default
+slot nhận thêm `rowIndex` và `columnIndex`.
+
 ### ChatVirtualScroll
 
 `ChatVirtualScroll` dành cho hội thoại có tin nhắn cao thấp khác nhau. Mặc định
@@ -717,8 +760,8 @@ Các component dùng container nhận một số hoặc chuỗi chiều cao CSS.
 
 Chiều cao phần trăm chỉ hoạt động khi thẻ cha có chiều cao xác định. Bản
 development cảnh báo nếu viewport được tính thành `0px`.
-`WindowDynamicVirtualScroll` dùng cửa sổ trình duyệt nên không có prop
-`height`.
+`WindowDynamicVirtualScroll` và `WindowGirdVirtualScroll` dùng cửa sổ trình
+duyệt nên không có prop `height`.
 
 ### Key ổn định cho item
 
@@ -778,8 +821,8 @@ phép request tiếp theo. Giữ `loading` là true trong toàn bộ request và
 
 ### Kéo để làm mới
 
-Pull-to-refresh có trên `VirtualList`, `DynamicVirtualScroll`, `VirtualScroll`
-và `WindowDynamicVirtualScroll`:
+Pull-to-refresh có trên `VirtualList`, `DynamicVirtualScroll`, `VirtualScroll`,
+`WindowDynamicVirtualScroll` và `WindowGirdVirtualScroll`:
 
 ```vue
 <VirtualList
@@ -820,6 +863,7 @@ import type {
   VirtualScrollExpose,
   VirtualScrollProps,
   WindowDynamicVirtualScrollProps,
+  WindowGirdVirtualScrollProps,
 } from 'vue-virtual-flow'
 ```
 

package/dist/components/WindowGirdVirtualScroll.d.cts

@@ -0,0 +1,53 @@
+import { ItemKey, ScrollAlignment, VirtualScrollEvent } from '../types.cjs';
+declare const _default: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
+        readonly onScroll?: ((event: VirtualScrollEvent) => any) | undefined;
+        readonly onLoadMore?: (() => any) | undefined;
+        readonly onRefresh?: (() => any) | undefined;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onScroll" | "onLoadMore" | "onRefresh"> & {
+        items: readonly T[];
+        itemSize: number;
+        columns?: number;
+        gap?: number;
+        overscan?: number;
+        itemKey?: ItemKey<T> extends infer Key ? Key : never;
+        ariaLabel?: string;
+        hasMore?: boolean;
+        loading?: boolean;
+        loadingItemSize?: number;
+        loadMoreThreshold?: number;
+        pullToRefresh?: boolean;
+        refreshing?: boolean;
+        pullRefreshThreshold?: number;
+    } & Partial<{}>> & import('vue').PublicProps;
+    expose(exposed: import('vue').ShallowUnwrapRef<{
+        scrollTo: (position: number, options?: ScrollToOptions) => void;
+        scrollToIndex: (index: number, options?: ScrollToOptions & {
+            align?: ScrollAlignment;
+        }) => void;
+        scrollToTop: (behavior?: ScrollBehavior) => void;
+    }>): void;
+    attrs: any;
+    slots: {
+        default(props: {
+            item: T;
+            index: number;
+            rowIndex: number;
+            columnIndex: number;
+        }): unknown;
+        empty?(): unknown;
+        loading?(): unknown;
+        refresh?(props: {
+            pullDistance: number;
+            progress: number;
+            refreshing: boolean;
+        }): unknown;
+    };
+    emit: ((evt: "scroll", event: VirtualScrollEvent) => void) & ((evt: "loadMore") => void) & ((evt: "refresh") => void);
+}>) => import('vue').VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+export default _default;
+type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/dist/components/WindowGirdVirtualScroll.d.ts

@@ -0,0 +1,53 @@
+import { ItemKey, ScrollAlignment, VirtualScrollEvent } from '../types.js';
+declare const _default: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
+        readonly onScroll?: ((event: VirtualScrollEvent) => any) | undefined;
+        readonly onLoadMore?: (() => any) | undefined;
+        readonly onRefresh?: (() => any) | undefined;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onScroll" | "onLoadMore" | "onRefresh"> & {
+        items: readonly T[];
+        itemSize: number;
+        columns?: number;
+        gap?: number;
+        overscan?: number;
+        itemKey?: ItemKey<T> extends infer Key ? Key : never;
+        ariaLabel?: string;
+        hasMore?: boolean;
+        loading?: boolean;
+        loadingItemSize?: number;
+        loadMoreThreshold?: number;
+        pullToRefresh?: boolean;
+        refreshing?: boolean;
+        pullRefreshThreshold?: number;
+    } & Partial<{}>> & import('vue').PublicProps;
+    expose(exposed: import('vue').ShallowUnwrapRef<{
+        scrollTo: (position: number, options?: ScrollToOptions) => void;
+        scrollToIndex: (index: number, options?: ScrollToOptions & {
+            align?: ScrollAlignment;
+        }) => void;
+        scrollToTop: (behavior?: ScrollBehavior) => void;
+    }>): void;
+    attrs: any;
+    slots: {
+        default(props: {
+            item: T;
+            index: number;
+            rowIndex: number;
+            columnIndex: number;
+        }): unknown;
+        empty?(): unknown;
+        loading?(): unknown;
+        refresh?(props: {
+            pullDistance: number;
+            progress: number;
+            refreshing: boolean;
+        }): unknown;
+    };
+    emit: ((evt: "scroll", event: VirtualScrollEvent) => void) & ((evt: "loadMore") => void) & ((evt: "refresh") => void);
+}>) => import('vue').VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+export default _default;
+type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/dist/index.d.cts

@@ -5,6 +5,7 @@ import { default as ShortMediaFeed } from './components/ShortMediaFeed.cjs';
 import { default as VirtualCarousel } from './components/VirtualCarousel.cjs';
 import { default as VirtualScroll } from './components/VirtualScroll.cjs';
 import { default as WindowDynamicVirtualScroll } from './components/WindowDynamicVirtualScroll.cjs';
+import { default as WindowGirdVirtualScroll } from './components/WindowGirdVirtualScroll.cjs';
 declare module 'vue' {
     interface GlobalComponents {
         ChatVirtualScroll: typeof ChatVirtualScroll;
@@ -14,10 +15,11 @@ declare module 'vue' {
         VirtualList: typeof DynamicVirtualScroll;
         VirtualScroll: typeof VirtualScroll;
         WindowDynamicVirtualScroll: typeof WindowDynamicVirtualScroll;
+        WindowGirdVirtualScroll: typeof WindowGirdVirtualScroll;
     }
 }
 declare const VirtualList: typeof DynamicVirtualScroll;
-export { ChatVirtualScroll, DynamicVirtualScroll, ShortMediaFeed, VirtualCarousel, VirtualList, VirtualScroll, WindowDynamicVirtualScroll, };
-export type { ChatVirtualScrollExpose, ChatVirtualScrollProps, DynamicVirtualScrollProps, ItemKey, ResponsiveBreakpoint, ScrollAlignment, ShortMediaFeedChangeEvent, ShortMediaFeedExpose, ShortMediaFeedProps, VirtualCarouselChangeEvent, VirtualCarouselExpose, VirtualCarouselProps, VirtualListExpose, VirtualListProps, VirtualScrollEvent, VirtualScrollExpose, VirtualScrollProps, WindowDynamicVirtualScrollProps, } from './types.cjs';
+export { ChatVirtualScroll, DynamicVirtualScroll, ShortMediaFeed, VirtualCarousel, VirtualList, VirtualScroll, WindowDynamicVirtualScroll, WindowGirdVirtualScroll, };
+export type { ChatVirtualScrollExpose, ChatVirtualScrollProps, DynamicVirtualScrollProps, ItemKey, ResponsiveBreakpoint, ScrollAlignment, ShortMediaFeedChangeEvent, ShortMediaFeedExpose, ShortMediaFeedProps, VirtualCarouselChangeEvent, VirtualCarouselExpose, VirtualCarouselProps, VirtualListExpose, VirtualListProps, VirtualScrollEvent, VirtualScrollExpose, VirtualScrollProps, WindowDynamicVirtualScrollProps, WindowGirdVirtualScrollProps, } from './types.cjs';
 export declare const VueVirtualScroll: Plugin;
 export default VueVirtualScroll;

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { default as ShortMediaFeed } from './components/ShortMediaFeed.js';
 import { default as VirtualCarousel } from './components/VirtualCarousel.js';
 import { default as VirtualScroll } from './components/VirtualScroll.js';
 import { default as WindowDynamicVirtualScroll } from './components/WindowDynamicVirtualScroll.js';
+import { default as WindowGirdVirtualScroll } from './components/WindowGirdVirtualScroll.js';
 declare module 'vue' {
     interface GlobalComponents {
         ChatVirtualScroll: typeof ChatVirtualScroll;
@@ -14,10 +15,11 @@ declare module 'vue' {
         VirtualList: typeof DynamicVirtualScroll;
         VirtualScroll: typeof VirtualScroll;
         WindowDynamicVirtualScroll: typeof WindowDynamicVirtualScroll;
+        WindowGirdVirtualScroll: typeof WindowGirdVirtualScroll;
     }
 }
 declare const VirtualList: typeof DynamicVirtualScroll;
-export { ChatVirtualScroll, DynamicVirtualScroll, ShortMediaFeed, VirtualCarousel, VirtualList, VirtualScroll, WindowDynamicVirtualScroll, };
-export type { ChatVirtualScrollExpose, ChatVirtualScrollProps, DynamicVirtualScrollProps, ItemKey, ResponsiveBreakpoint, ScrollAlignment, ShortMediaFeedChangeEvent, ShortMediaFeedExpose, ShortMediaFeedProps, VirtualCarouselChangeEvent, VirtualCarouselExpose, VirtualCarouselProps, VirtualListExpose, VirtualListProps, VirtualScrollEvent, VirtualScrollExpose, VirtualScrollProps, WindowDynamicVirtualScrollProps, } from './types.js';
+export { ChatVirtualScroll, DynamicVirtualScroll, ShortMediaFeed, VirtualCarousel, VirtualList, VirtualScroll, WindowDynamicVirtualScroll, WindowGirdVirtualScroll, };
+export type { ChatVirtualScrollExpose, ChatVirtualScrollProps, DynamicVirtualScrollProps, ItemKey, ResponsiveBreakpoint, ScrollAlignment, ShortMediaFeedChangeEvent, ShortMediaFeedExpose, ShortMediaFeedProps, VirtualCarouselChangeEvent, VirtualCarouselExpose, VirtualCarouselProps, VirtualListExpose, VirtualListProps, VirtualScrollEvent, VirtualScrollExpose, VirtualScrollProps, WindowDynamicVirtualScrollProps, WindowGirdVirtualScrollProps, } from './types.js';
 export declare const VueVirtualScroll: Plugin;
 export default VueVirtualScroll;

package/dist/types.d.cts

@@ -43,6 +43,22 @@ export interface WindowDynamicVirtualScrollProps<T> {
     refreshing?: boolean;
     pullRefreshThreshold?: number;
 }
+export interface WindowGirdVirtualScrollProps<T> {
+    items: readonly T[];
+    itemSize: number;
+    columns?: number;
+    gap?: number;
+    overscan?: number;
+    itemKey?: ItemKey<T>;
+    ariaLabel?: string;
+    hasMore?: boolean;
+    loading?: boolean;
+    loadingItemSize?: number;
+    loadMoreThreshold?: number;
+    pullToRefresh?: boolean;
+    refreshing?: boolean;
+    pullRefreshThreshold?: number;
+}
 export interface ChatVirtualScrollProps<T> {
     items: readonly T[];
     estimatedItemSize?: number;

package/dist/types.d.ts

@@ -43,6 +43,22 @@ export interface WindowDynamicVirtualScrollProps<T> {
     refreshing?: boolean;
     pullRefreshThreshold?: number;
 }
+export interface WindowGirdVirtualScrollProps<T> {
+    items: readonly T[];
+    itemSize: number;
+    columns?: number;
+    gap?: number;
+    overscan?: number;
+    itemKey?: ItemKey<T>;
+    ariaLabel?: string;
+    hasMore?: boolean;
+    loading?: boolean;
+    loadingItemSize?: number;
+    loadMoreThreshold?: number;
+    pullToRefresh?: boolean;
+    refreshing?: boolean;
+    pullRefreshThreshold?: number;
+}
 export interface ChatVirtualScrollProps<T> {
     items: readonly T[];
     estimatedItemSize?: number;