virtua 0.52.10 → 0.53.0

package/lib/react/VMasonry.d.ts

@@ -0,0 +1,105 @@
+import { ReactElement, Ref } from 'react';
+import { CacheSnapshot, ScrollToIndexOpts } from '../core/index.js';
+import { ViewportComponentAttributes } from './types.js';
+/**
+ * Methods of {@link VMasonry}.
+ */
+export interface VMasonryHandle {
+    /**
+     * Get current {@link CacheSnapshot}.
+     */
+    readonly cache: CacheSnapshot;
+    /**
+     * Get current scrollTop.
+     */
+    readonly scrollOffset: number;
+    /**
+     * Get current scrollHeight.
+     */
+    readonly scrollSize: number;
+    /**
+     * Get current clientHeight.
+     */
+    readonly viewportSize: number;
+    /**
+     * Get item offset from start.
+     * @param index index of item
+     */
+    getItemOffset(index: number): number;
+    /**
+     * Get item size.
+     * @param index index of item
+     */
+    getItemSize(index: number): number;
+    /**
+     * Scroll to the item specified by index.
+     * @param index index of item
+     * @param opts options
+     */
+    scrollToIndex(index: number, opts?: ScrollToIndexOpts): void;
+    /**
+     * Scroll to the given offset.
+     * @param offset offset from start
+     */
+    scrollTo(offset: number): void;
+    /**
+     * Scroll by the given offset.
+     * @param offset offset from current position
+     */
+    scrollBy(offset: number): void;
+}
+/**
+ * Props of {@link VMasonry}.
+ */
+export interface VMasonryProps<T> extends ViewportComponentAttributes {
+    /**
+     * The elements renderer function.
+     */
+    children: (data: T, index: number) => ReactElement;
+    /**
+     * The data items rendered by this component.
+     */
+    data: ArrayLike<T>;
+    /**
+     * The number of lanes (columns) which items are laid out into. Each item is placed into the shortest lane in order. It must be an integer and the minimum value is 1.
+     */
+    lanes: number;
+    /**
+     * The gap between the items and the lanes in pixels, which is not included in the sizes.
+     * @defaultValue 0
+     */
+    gap?: number;
+    /**
+     * Item size hint for unmeasured items in pixels. It will help to reduce scroll jump when items are measured if used properly.
+     *
+     * - If not set, initial item sizes will be automatically estimated from measured sizes. This is recommended for most cases.
+     * - If set, you can opt out estimation and use the value as initial item size.
+     */
+    itemSize?: number;
+    /**
+     * Extra item space in pixels to render before/after the viewport. The minimum value is 0. Lower value will give better performance but you can increase to avoid showing blank items in fast scrolling.
+     * @defaultValue 200
+     */
+    bufferSize?: number;
+    /**
+     * You can restore cache by passing a {@link CacheSnapshot} on mount. This is useful when you want to restore scroll position after navigation. The snapshot can be obtained from {@link VMasonryHandle.cache}.
+     *
+     * **The length of items should be the same as when you take the snapshot, otherwise restoration may not work as expected.**
+     */
+    cache?: CacheSnapshot;
+    /**
+     * Callback invoked whenever scroll offset changes.
+     * @param offset Current scrollTop.
+     */
+    onScroll?: (offset: number) => void;
+    /**
+     * Callback invoked when scrolling stops.
+     */
+    onScrollEnd?: () => void;
+}
+/**
+ * Virtualized masonry component. See {@link VMasonryProps} and {@link VMasonryHandle}.
+ */
+export declare const VMasonry: <T>(props: VMasonryProps<T> & {
+    ref?: Ref<VMasonryHandle>;
+}) => ReactElement;

package/lib/react/Virtualizer.d.ts

@@ -80,7 +80,9 @@ export interface VirtualizerProps<T = unknown> {
      */
     itemSize?: number;
     /**
-     * While true is set, scroll position will be maintained from the end not usual start when items are added to/removed from start. It's recommended to set false if you add to/remove from mid/end of the list because it can cause unexpected behavior. This prop is useful for reverse infinite scrolling.
+     * Set true only when items are added to or removed from the start of the list, such as when older items are loaded in reverse infinite scrolling. In that case, the scroll position is maintained from the end of the list instead of the start.
+     *
+     * **Do not set true in any other case, as it can cause unexpected behavior.**
      */
     shift?: boolean;
     /**

package/lib/react/WindowVirtualizer.d.ts

@@ -66,7 +66,9 @@ export interface WindowVirtualizerProps<T = unknown> {
      */
     itemSize?: number;
     /**
-     * While true is set, scroll position will be maintained from the end not usual start when items are added to/removed from start. It's recommended to set false if you add to/remove from mid/end of the list because it can cause unexpected behavior. This prop is useful for reverse infinite scrolling.
+     * Set true only when items are added to or removed from the start of the list, such as when older items are loaded in reverse infinite scrolling. In that case, the scroll position is maintained from the end of the list instead of the start.
+     *
+     * **Do not set true in any other case, as it can cause unexpected behavior.**
      */
     shift?: boolean;
     /**

package/lib/react/index.d.ts

@@ -7,4 +7,6 @@ export type { WindowVirtualizerProps, WindowVirtualizerHandle, } from './WindowV
 export { VGrid } from './VGrid.js';
 export type { VGridProps, VGridHandle } from './VGrid.js';
 export type { GridSize, GridSpan } from '../core/index.js';
+export { VMasonry } from './VMasonry.js';
+export type { VMasonryProps, VMasonryHandle } from './VMasonry.js';
 export type * from './types.js';

package/lib/react/types.d.ts

@@ -1,5 +1,5 @@
 import { ComponentType, CSSProperties, LegacyRef, ReactNode } from 'react';
-export type ViewportComponentAttributes = Pick<React.HTMLAttributes<HTMLElement>, "className" | "style" | "id" | "role" | "tabIndex" | "onKeyDown" | "onWheel"> & React.AriaAttributes;
+export type ViewportComponentAttributes = Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "onScroll" | "onScrollEnd">;
 export interface CustomContainerComponentProps {
     style: CSSProperties;
     children: ReactNode;

package/lib/solid/VMasonry.d.ts

@@ -0,0 +1,107 @@
+import { JSX, Accessor } from 'solid-js';
+import { ScrollToIndexOpts, CacheSnapshot } from '../core/index.js';
+import { ViewportComponentAttributes } from './types.js';
+/**
+ * Methods of {@link VMasonry}.
+ */
+export interface VMasonryHandle {
+    /**
+     * Get current {@link CacheSnapshot}.
+     */
+    readonly cache: CacheSnapshot;
+    /**
+     * Get current scrollTop.
+     */
+    readonly scrollOffset: number;
+    /**
+     * Get current scrollHeight.
+     */
+    readonly scrollSize: number;
+    /**
+     * Get current clientHeight.
+     */
+    readonly viewportSize: number;
+    /**
+     * Get item offset from start.
+     * @param index index of item
+     */
+    getItemOffset(index: number): number;
+    /**
+     * Get item size.
+     * @param index index of item
+     */
+    getItemSize(index: number): number;
+    /**
+     * Scroll to the item specified by index.
+     * @param index index of item
+     * @param opts options
+     */
+    scrollToIndex(index: number, opts?: ScrollToIndexOpts): void;
+    /**
+     * Scroll to the given offset.
+     * @param offset offset from start
+     */
+    scrollTo(offset: number): void;
+    /**
+     * Scroll by the given offset.
+     * @param offset offset from current position
+     */
+    scrollBy(offset: number): void;
+}
+/**
+ * Props of {@link VMasonry}.
+ */
+export interface VMasonryProps<T> extends ViewportComponentAttributes {
+    /**
+     * Get reference to {@link VMasonryHandle}.
+     */
+    ref?: VMasonryHandle | ((handle?: VMasonryHandle) => void);
+    /**
+     * The data items rendered by this component.
+     */
+    data: readonly T[];
+    /**
+     * The elements renderer function.
+     */
+    children: (data: T, index: Accessor<number>) => JSX.Element;
+    /**
+     * The number of lanes (columns) which items are laid out into. Each item is placed into the shortest lane in order. It must be an integer and the minimum value is 1.
+     */
+    lanes: number;
+    /**
+     * The gap between the items and the lanes in pixels, which is not included in the sizes.
+     * @defaultValue 0
+     */
+    gap?: number;
+    /**
+     * Item size hint for unmeasured items in pixels. It will help to reduce scroll jump when items are measured if used properly.
+     *
+     * - If not set, initial item sizes will be automatically estimated from measured sizes. This is recommended for most cases.
+     * - If set, you can opt out estimation and use the value as initial item size.
+     */
+    itemSize?: number;
+    /**
+     * Extra item space in pixels to render before/after the viewport. The minimum value is 0. Lower value will give better performance but you can increase to avoid showing blank items in fast scrolling.
+     * @defaultValue 200
+     */
+    bufferSize?: number;
+    /**
+     * You can restore cache by passing a {@link CacheSnapshot} on mount. This is useful when you want to restore scroll position after navigation. The snapshot can be obtained from {@link VMasonryHandle.cache}.
+     *
+     * **The length of items should be the same as when you take the snapshot, otherwise restoration may not work as expected.**
+     */
+    cache?: CacheSnapshot;
+    /**
+     * Callback invoked whenever scroll offset changes.
+     * @param offset Current scrollTop.
+     */
+    onScroll?: (offset: number) => void;
+    /**
+     * Callback invoked when scrolling stops.
+     */
+    onScrollEnd?: () => void;
+}
+/**
+ * Virtualized masonry component. See {@link VMasonryProps} and {@link VMasonryHandle}.
+ */
+export declare const VMasonry: <T>(props: VMasonryProps<T>) => JSX.Element;

package/lib/solid/Virtualizer.d.ts

@@ -99,7 +99,9 @@ export interface VirtualizerProps<T> {
      */
     ssrCount?: number;
     /**
-     * While true is set, scroll position will be maintained from the end not usual start when items are added to/removed from start. It's recommended to set false if you add to/remove from mid/end of the list because it can cause unexpected behavior. This prop is useful for reverse infinite scrolling.
+     * Set true only when items are added to or removed from the start of the list, such as when older items are loaded in reverse infinite scrolling. In that case, the scroll position is maintained from the end of the list instead of the start.
+     *
+     * **Do not set true in any other case, as it can cause unexpected behavior.**
      */
     shift?: boolean;
     /**

package/lib/solid/WindowVirtualizer.d.ts

@@ -71,7 +71,9 @@ export interface WindowVirtualizerProps<T> {
      */
     ssrCount?: number;
     /**
-     * While true is set, scroll position will be maintained from the end not usual start when items are added to/removed from start. It's recommended to set false if you add to/remove from mid/end of the list because it can cause unexpected behavior. This prop is useful for reverse infinite scrolling.
+     * Set true only when items are added to or removed from the start of the list, such as when older items are loaded in reverse infinite scrolling. In that case, the scroll position is maintained from the end of the list instead of the start.
+     *
+     * **Do not set true in any other case, as it can cause unexpected behavior.**
      */
     shift?: boolean;
     /**