virtua 0.52.9 → 0.53.0

package/lib/solid/types.d.ts

@@ -1,5 +1,5 @@
 import { JSX, ParentComponent } from 'solid-js';
-export type ViewportComponentAttributes = Pick<JSX.HTMLAttributes<HTMLElement>, "class" | "id" | "role" | "tabIndex" | "onKeyDown" | "onWheel"> & JSX.AriaAttributes & {
+export type ViewportComponentAttributes = Omit<JSX.HTMLAttributes<HTMLDivElement>, "ref" | "children" | "style" | "onScroll" | "onScrollEnd"> & {
     style?: JSX.CSSProperties;
 };
 export interface CustomContainerComponentProps {

package/lib/svelte/MasonryItem.svelte

@@ -0,0 +1,49 @@
+<script lang="ts" generics="T">
+  import { type Snippet } from "svelte";
+  import { type Driver } from "../core/index.js";
+  import { styleToString } from "./utils.js";
+
+  interface Props {
+    children: Snippet<[item: T, index: number]>;
+    item: T;
+    index: number;
+    offset: number;
+    crossOffset: string;
+    crossSize: string;
+    hide: boolean;
+    resizer: Driver["$observeItem"];
+  }
+
+  let {
+    children,
+    item,
+    index,
+    offset,
+    crossOffset,
+    crossSize,
+    hide,
+    resizer,
+  }: Props = $props();
+
+  let elementRef: HTMLDivElement;
+
+  // The index may be changed if elements are inserted to or removed from the start of data
+  $effect(() => {
+    return resizer(elementRef, index);
+  });
+
+  let style: string = $derived(
+    styleToString({
+      contain: "layout style",
+      position: "absolute",
+      top: offset + "px",
+      "inset-inline-start": crossOffset,
+      width: crossSize,
+      visibility: hide ? "hidden" : undefined,
+    }),
+  );
+</script>
+
+<div bind:this={elementRef} {style}>
+  {@render children(item, index)}
+</div>

package/lib/svelte/VGrid.svelte

@@ -187,7 +187,7 @@
     return styleToString({
       // https://github.com/inokawa/virtua/pull/775 https://github.com/inokawa/virtua/issues/800
       contain: "size style",
-      "overflow-anchor": "none", // opt out browser's scroll anchoring because it will conflict to scroll anchoring of virtualizer
+      "overflow-anchor": "none", // opt out browser's scroll anchoring because it will conflict with scroll anchoring of virtualizer
       flex: "none", // flex style can break layout
       display: "grid",
       "grid-template-rows": rowTemplate,

package/lib/svelte/VList.svelte

@@ -58,7 +58,7 @@
     )) satisfies VListHandle["scrollBy"] as VListHandle["scrollBy"];
 
   const viewportStyle = styleToString({
-    display: horizontal ? "inline-block" : "block",
+    display: "block",
     [horizontal ? "overflow-x" : "overflow-y"]: "auto",
     contain: "strict",
     width: "100%",

package/lib/svelte/VMasonry.svelte

@@ -0,0 +1,182 @@
+<script lang="ts" generics="T">
+  import { onMount, onDestroy } from "svelte";
+  import {
+    type ItemsRange,
+    type StateVersion,
+    UPDATE_SCROLL_END_EVENT,
+    UPDATE_SCROLL_EVENT,
+    UPDATE_VIRTUAL_STATE,
+    createContainerDriver,
+    createMasonryLayout,
+    ACTION_ITEMS_LENGTH_CHANGE,
+    ACTION_RELAYOUT,
+    createVirtualStore,
+    getScrollSize as _getScrollSize,
+    scrollTo as _scrollTo,
+    scrollBy as _scrollBy,
+    scrollToIndex as _scrollToIndex,
+  } from "../core/index.js";
+  import { defaultGetKey, isSameRange, styleToString } from "./utils.js";
+  import MasonryItem from "./MasonryItem.svelte";
+  import type { VMasonryHandle, VMasonryProps } from "./VMasonry.type.js";
+
+  const toCrossValue = (fraction: number, px: number): string =>
+    px ? `calc(${fraction * 100}% + ${px}px)` : fraction * 100 + "%";
+
+  interface Props extends VMasonryProps<T> {}
+
+  let {
+    data,
+    getKey = defaultGetKey,
+    lanes: lanesProp,
+    gap: gapProp,
+    itemSize,
+    bufferSize,
+    cache,
+    children,
+    onscroll,
+    onscrollend,
+    ...rest
+  }: Props = $props();
+
+  const layout = createMasonryLayout(
+    data.length,
+    lanesProp,
+    gapProp,
+    itemSize,
+    cache,
+  );
+  const store = createVirtualStore(layout);
+  const driver = createContainerDriver(store, false);
+  store.$subscribe(UPDATE_VIRTUAL_STATE, () => {
+    stateVersion = store.$getStateVersion();
+  });
+  store.$subscribe(UPDATE_SCROLL_EVENT, () => {
+    onscroll && onscroll(store.$getScrollOffset());
+  });
+  store.$subscribe(UPDATE_SCROLL_END_EVENT, () => {
+    onscrollend && onscrollend();
+  });
+
+  let containerRef: HTMLDivElement | undefined = $state();
+
+  let stateVersion: StateVersion = $state(store.$getStateVersion());
+
+  let prevRange: ItemsRange | undefined;
+  let range = $derived.by(() => {
+    stateVersion;
+    const next = store.$getRange(bufferSize);
+    if (prevRange && isSameRange(prevRange, next)) {
+      return prevRange;
+    }
+    return (prevRange = next);
+  });
+  let isScrolling = $derived(stateVersion && store.$isScrolling());
+  let totalSize = $derived(stateVersion && store.$getTotalSize());
+  let lanes = $derived(stateVersion && layout.$getLanes());
+  let gap = $derived(stateVersion && layout.$getGap());
+  // The lanes share the width left by the gaps between them
+  let crossSize = $derived(toCrossValue(1 / lanes, gap / lanes - gap));
+
+  let indexes = $derived.by(() => {
+    const len = data.length;
+    const [start, end] = range;
+    const arr: number[] = [];
+    for (let i = start; i <= end; i++) {
+      // Guard for experimental.async: true, which runs the each block before $effect.pre
+      // https://github.com/inokawa/virtua/pull/847
+      if (i < len) {
+        arr.push(i);
+      }
+    }
+    return arr;
+  });
+
+  onMount(() => {
+    driver.$observe(containerRef!);
+  });
+  onDestroy(() => {
+    store.$dispose();
+    driver.$dispose();
+  });
+
+  $effect.pre(() => {
+    if (data.length !== store.$getItemsLength()) {
+      store.$update(ACTION_ITEMS_LENGTH_CHANGE, [data.length]);
+    }
+  });
+  $effect.pre(() => {
+    layout.$setOptions(lanesProp, gapProp);
+    store.$update(ACTION_RELAYOUT, undefined);
+  });
+
+  let prevStateVersion: StateVersion | undefined;
+  $effect(() => {
+    if (prevStateVersion === stateVersion) return;
+    prevStateVersion = stateVersion;
+    driver.$effect();
+  });
+
+  export const getCache =
+    layout.$snapshot satisfies VMasonryHandle["getCache"] as VMasonryHandle["getCache"];
+  export const getScrollOffset =
+    store.$getScrollOffset satisfies VMasonryHandle["getScrollOffset"] as VMasonryHandle["getScrollOffset"];
+  export const getScrollSize = (() =>
+    _getScrollSize(
+      store,
+    )) satisfies VMasonryHandle["getScrollSize"] as VMasonryHandle["getScrollSize"];
+  export const getViewportSize =
+    store.$getViewportSize satisfies VMasonryHandle["getViewportSize"] as VMasonryHandle["getViewportSize"];
+  export const getItemOffset =
+    store.$getItemOffset satisfies VMasonryHandle["getItemOffset"] as VMasonryHandle["getItemOffset"];
+  export const getItemSize =
+    store.$getItemSize satisfies VMasonryHandle["getItemSize"] as VMasonryHandle["getItemSize"];
+  export const scrollToIndex: VMasonryHandle["scrollToIndex"] = (index, opts) =>
+    _scrollToIndex(driver, store, index, opts);
+  export const scrollTo: VMasonryHandle["scrollTo"] = (offset) =>
+    _scrollTo(driver, offset);
+  export const scrollBy: VMasonryHandle["scrollBy"] = (offset) =>
+    _scrollBy(driver, store, offset);
+
+  const viewportStyle = styleToString({
+    display: "block",
+    "overflow-y": "auto",
+    contain: "strict",
+    width: "100%",
+    height: "100%",
+  });
+  let containerStyle = $derived(
+    styleToString({
+      contain: "size style", // https://github.com/inokawa/virtua/pull/775 https://github.com/inokawa/virtua/issues/800
+      "overflow-anchor": "none", // opt out browser's scroll anchoring because it will conflict with scroll anchoring of virtualizer
+      flex: "none", // flex style can break layout
+      position: "relative",
+      width: "100%",
+      height: totalSize + "px",
+      "pointer-events": isScrolling ? "none" : undefined,
+    }),
+  );
+</script>
+
+<!--
+  @component
+  Virtualized masonry component. See {@link VMasonryProps} and {@link VMasonryHandle}.
+-->
+<div {...rest} style="{viewportStyle} {rest.style || ''}">
+  <div bind:this={containerRef} style={containerStyle}>
+    {#each indexes as index (getKey(data[index]!, index))}
+      {@const item = data[index]!}
+      {@const lane = stateVersion && layout.$getItemLane(index)}
+      <MasonryItem
+        {children}
+        {item}
+        {index}
+        offset={stateVersion && store.$getItemOffset(index)}
+        crossOffset={toCrossValue(lane / lanes, (lane * gap) / lanes)}
+        {crossSize}
+        hide={stateVersion && store.$isUnmeasuredItem(index)}
+        resizer={driver.$observeItem}
+      />
+    {/each}
+  </div>
+</div>

package/lib/svelte/VMasonry.type.d.ts

@@ -0,0 +1,104 @@
+import { Snippet } from 'svelte';
+import { CacheSnapshot, ScrollToIndexOpts } from '../core/index.js';
+import { ViewportComponentAttributes } from './types.js';
+/**
+ * Props of {@link VMasonry}.
+ */
+export interface VMasonryProps<T> extends ViewportComponentAttributes {
+    /**
+     * The data items rendered by this component.
+     */
+    data: readonly T[];
+    /**
+     * The elements renderer snippet.
+     */
+    children: Snippet<[item: T, index: number]>;
+    /**
+     * Function that returns the key of an item in the list. It's recommended to specify whenever possible for performance.
+     * @default defaultGetKey (returns index of item)
+     */
+    getKey?: (data: T, index: number) => string | number;
+    /**
+     * 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.getCache}.
+     *
+     * **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;
+}
+/**
+ * Methods of {@link VMasonry}.
+ */
+export interface VMasonryHandle {
+    /**
+     * Get current {@link CacheSnapshot}.
+     */
+    getCache: () => CacheSnapshot;
+    /**
+     * Get current scrollTop.
+     */
+    getScrollOffset: () => number;
+    /**
+     * Get current scrollHeight.
+     */
+    getScrollSize: () => number;
+    /**
+     * Get current clientHeight.
+     */
+    getViewportSize: () => 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;
+}

package/lib/svelte/Virtualizer.svelte

@@ -171,7 +171,7 @@
   let containerStyle = $derived(
     styleToString({
       contain: "size style", // https://github.com/inokawa/virtua/pull/775 https://github.com/inokawa/virtua/issues/800
-      "overflow-anchor": "none", // opt out browser's scroll anchoring because it will conflict to scroll anchoring of virtualizer
+      "overflow-anchor": "none", // opt out browser's scroll anchoring because it will conflict with scroll anchoring of virtualizer
       flex: "none", // flex style can break layout
       position: "relative",
       width: horizontal ? totalSize + "px" : "100%",

package/lib/svelte/Virtualizer.type.d.ts

@@ -54,7 +54,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/svelte/WindowVirtualizer.svelte

@@ -126,7 +126,7 @@
   let containerStyle = $derived(
     styleToString({
       contain: "size style", // https://github.com/inokawa/virtua/pull/775 https://github.com/inokawa/virtua/issues/800
-      "overflow-anchor": "none", // opt out browser's scroll anchoring because it will conflict to scroll anchoring of virtualizer
+      "overflow-anchor": "none", // opt out browser's scroll anchoring because it will conflict with scroll anchoring of virtualizer
       flex: "none", // flex style can break layout
       position: "relative",
       width: horizontal ? totalSize + "px" : "100%",

package/lib/svelte/WindowVirtualizer.type.d.ts

@@ -34,7 +34,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;
     /**

package/lib/svelte/index.d.ts

@@ -10,3 +10,5 @@ export type { WindowVirtualizerProps, WindowVirtualizerHandle, } from './WindowV
 export { default as VGrid } from './VGrid.svelte';
 export type { VGridProps, VGridHandle } from './VGrid.type.js';
 export type { GridSize, GridSpan } from '../core/index.js';
+export { default as VMasonry } from './VMasonry.svelte';
+export type { VMasonryProps, VMasonryHandle } from './VMasonry.type.js';

package/lib/svelte/index.js

@@ -2,4 +2,5 @@ import VList from "./VList.svelte";
 import Virtualizer from "./Virtualizer.svelte";
 import WindowVirtualizer from "./WindowVirtualizer.svelte";
 import VGrid from "./VGrid.svelte";
-export { VGrid, VList, Virtualizer, WindowVirtualizer };
+import VMasonry from "./VMasonry.svelte";
+export { VGrid, VList, VMasonry, Virtualizer, WindowVirtualizer };

package/lib/svelte/types.d.ts

@@ -1,2 +1,2 @@
-import { HTMLAttributes, AriaAttributes } from 'svelte/elements';
-export type ViewportComponentAttributes = Pick<HTMLAttributes<HTMLElement>, "class" | "style" | "id" | "role" | "tabindex"> & AriaAttributes;
+import { HTMLAttributes } from 'svelte/elements';
+export type ViewportComponentAttributes = Omit<HTMLAttributes<HTMLDivElement>, "children" | "onscroll" | "onscrollend">;

package/lib/vue/VMasonry.d.ts

@@ -0,0 +1,110 @@
+import { VNode, PublicProps } from 'vue';
+import { ScrollToIndexOpts, CacheSnapshot } from '../core/index.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 PublicProps {
+    /**
+     * The data items rendered by this component.
+     */
+    data: 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;
+}
+interface VMasonryInstance<T> extends VMasonryHandle {
+    $props: VMasonryProps<T>;
+    $slots: {
+        default: (arg: {
+            item: T;
+            index: number;
+        }) => VNode[];
+    };
+}
+/**
+ * Virtualized masonry component. See {@link VMasonryProps} and {@link VMasonryHandle}.
+ */
+export declare const VMasonry: {
+    new <T>(props: VMasonryProps<T>): VMasonryInstance<T>;
+};
+export {};

package/lib/vue/Virtualizer.d.ts

@@ -22,7 +22,9 @@ export interface VirtualizerProps<T = unknown> extends PublicProps {
      */
     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/vue/WindowVirtualizer.d.ts

@@ -25,7 +25,9 @@ export interface WindowVirtualizerProps<T = unknown> extends PublicProps {
      */
     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;
     /**