virtua 0.35.1 → 0.36.0

package/lib/svelte/ListItem.svelte

@@ -1,20 +1,37 @@
-<script lang="ts">
-  import { afterUpdate, onDestroy } from "svelte";
+<script lang="ts" generics="T">
+  import { type Snippet, onDestroy } from "svelte";
   import { isRTLDocument, type ItemResizeObserver } from "./core";
   import { styleToString } from "./utils";
+  import type { SvelteHTMLElements } from "svelte/elements";
 
-  export let index: number;
-  export let offset: number;
-  export let hide: boolean;
-  export let horizontal: boolean;
-  export let resizer: ItemResizeObserver;
+  interface Props {
+    children: Snippet<[item: T, index: number]>;
+    item: T;
+    as: keyof SvelteHTMLElements | undefined;
+    index: number;
+    offset: number;
+    hide: boolean;
+    horizontal: boolean;
+    resizer: ItemResizeObserver;
+  }
+
+  let {
+    children,
+    item,
+    as = "div",
+    index,
+    offset,
+    hide,
+    horizontal,
+    resizer,
+  }: Props = $props();
 
   let elementRef: HTMLDivElement;
 
   let cleanupResizer: (() => void) | undefined;
   // The index may be changed if elements are inserted to or removed from the start of props.children
   let prevIndex: number | undefined;
-  afterUpdate(() => {
+  $effect(() => {
     if (prevIndex === index) return;
     if (cleanupResizer) cleanupResizer();
     cleanupResizer = resizer(elementRef, (prevIndex = index));
@@ -23,8 +40,7 @@
     if (cleanupResizer) cleanupResizer();
   });
 
-  let style: string;
-  $: {
+  let style: string = $derived.by(() => {
     const _style: Record<string, string> = {
       position: "absolute",
       [horizontal ? "height" : "width"]: "100%",
@@ -37,10 +53,10 @@
       _style["display"] = "flex";
     }
 
-    style = styleToString(_style);
-  }
+    return styleToString(_style);
+  });
 </script>
 
-<div bind:this={elementRef} {style}>
-  <slot />
-</div>
+<svelte:element this={as} bind:this={elementRef} {style}>
+  {@render children(item, index)}
+</svelte:element>

package/lib/svelte/ListItem.svelte.d.ts

@@ -1,25 +1,29 @@
-import { SvelteComponent } from "svelte";
+import { type Snippet } from "svelte";
 import { type ItemResizeObserver } from "./core";
-declare const __propDef: {
-    props: {
+import type { SvelteHTMLElements } from "svelte/elements";
+declare class __sveltets_Render<T> {
+    props(): {
+        children: Snippet<[item: T, index: number]>;
+        item: T;
+        as: keyof SvelteHTMLElements | undefined;
         index: number;
         offset: number;
         hide: boolean;
         horizontal: boolean;
         resizer: ItemResizeObserver;
     };
-    events: {
-        [evt: string]: CustomEvent<any>;
-    };
-    slots: {
-        default: {};
-    };
-    exports?: {} | undefined;
-    bindings?: string | undefined;
-};
-export type ListItemProps = typeof __propDef.props;
-export type ListItemEvents = typeof __propDef.events;
-export type ListItemSlots = typeof __propDef.slots;
-export default class ListItem extends SvelteComponent<ListItemProps, ListItemEvents, ListItemSlots> {
+    events(): {};
+    slots(): {};
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
 }
-export {};
+declare const ListItem: $$IsomorphicComponent;
+type ListItem<T> = InstanceType<typeof ListItem<T>>;
+export default ListItem;

package/lib/svelte/VList.svelte

@@ -1,197 +1,44 @@
 <script lang="ts" generics="T">
-  import { onMount, onDestroy, createEventDispatcher } from "svelte";
-  import type { HTMLAttributes } from "svelte/elements";
-  import {
-    SCROLL_IDLE,
-    type StateVersion,
-    getOverscanedRange,
-    CHANGE_ITEM_LENGTH,
-    createVirtualizer,
-    FIX_SCROLL_JUMP,
-    GET_ITEM_OFFSET,
-    GET_JUMP_COUNT,
-    GET_RANGE,
-    GET_SCROLL_DIRECTION,
-    GET_SCROLL_OFFSET,
-    GET_SCROLL_SIZE,
-    GET_TOTAL_SIZE,
-    GET_VIEWPORT_SIZE,
-    IS_ITEM_HIDDEN,
-    OBSERVE_ITEM_RESIZE,
-    ON_MOUNT,
-    ON_UN_MOUNT,
-    SCROLL_BY,
-    SCROLL_TO,
-    SCROLL_TO_INDEX,
-  } from "./core";
-  import {
-    onUpdate,
-    type UnwrapCustomEvents,
-    defaultGetKey,
-    styleToString,
-  } from "./utils";
-  import ListItem from "./ListItem.svelte";
+  import { styleToString } from "./utils";
+  import Virtualizer from "./Virtualizer.svelte";
+  import type { VListProps, VListHandle } from "./VList.type";
 
-  // https://github.com/sveltejs/rfcs/pull/38
-  interface $$Slots {
-    default: { item: T; index: number };
-  }
-  interface $$Props extends HTMLAttributes<HTMLDivElement> {
-    /**
-     * The data items rendered by this component.
-     */
-    data: T[];
-    /**
-     * 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;
-    /**
-     * Number of items to render above/below the visible bounds of the list. You can increase to avoid showing blank items in fast scrolling.
-     * @defaultValue 4
-     */
-    overscan?: number;
-    /**
-     * Item size hint for unmeasured items. 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;
-    /**
-     * 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.
-     */
-    shift?: boolean;
-    /**
-     * If true, rendered as a horizontally scrollable list. Otherwise rendered as a vertically scrollable list.
-     */
-    horizontal?: boolean;
-  }
+  interface Props extends VListProps<T> {}
 
-  // https://github.com/kitschpatrol/svelte-tweakpane-ui/blob/248fd7c24926af1e485a0676b6a8c053177e92db/src/lib/control/Button.svelte#L50-L51
-  interface $$Events {
-    /**
-     * Callback invoked whenever scroll offset changes.
-     * @param offset Current scrollTop or scrollLeft.
-     */
-    scroll: CustomEvent<number>;
-    /**
-     * Callback invoked when scrolling stops.
-     */
-    scrollEnd: CustomEvent<void>;
-    /**
-     * Callback invoked when visible items range changes.
-     */
-    rangeChange: CustomEvent<[start: number, end: number]>;
-  }
-
-  export let data: $$Props["data"];
-  export let getKey: NonNullable<$$Props["getKey"]> = defaultGetKey;
-  export let overscan: NonNullable<$$Props["overscan"]> = 4;
-  export let itemSize: $$Props["itemSize"] = undefined;
-  export let shift: NonNullable<$$Props["shift"]> = false;
-  export let horizontal: NonNullable<$$Props["horizontal"]> = false;
-
-  let containerRef: HTMLDivElement;
-
-  let rerender: StateVersion = [];
-
-  const dispatchEvent = createEventDispatcher<UnwrapCustomEvents<$$Events>>();
-
-  const virtualizer = createVirtualizer(
-    data.length,
+  let {
+    data,
+    getKey,
+    overscan,
     itemSize,
+    shift,
     horizontal,
-    (v) => {
-      rerender = v;
-    },
-    (offset) => {
-      dispatchEvent("scroll", offset);
-    },
-    () => {
-      dispatchEvent("scrollEnd");
-    }
-  );
-
-  $: range = rerender && virtualizer[GET_RANGE]();
-  $: scrollDirection = rerender && virtualizer[GET_SCROLL_DIRECTION]();
-  $: totalSize = rerender && virtualizer[GET_TOTAL_SIZE]();
-  $: jumpCount = rerender && virtualizer[GET_JUMP_COUNT]();
-  $: extendedRange = getOverscanedRange(
-    range[0],
-    range[1],
-    overscan,
-    scrollDirection,
-    data.length
-  );
-
-  onMount(() => {
-    const root = containerRef.parentElement!;
-    virtualizer[ON_MOUNT](root);
-  });
-  onDestroy(() => {
-    virtualizer[ON_UN_MOUNT]();
-  });
-
-  let prevLength = data.length;
-  onUpdate(() => {
-    if (prevLength === data.length) return;
-    virtualizer[CHANGE_ITEM_LENGTH]((prevLength = data.length), shift);
-  }, true);
-
-  let prevJumpCount: number | undefined;
-  onUpdate(() => {
-    if (prevJumpCount === jumpCount) return;
-    prevJumpCount = jumpCount;
-    virtualizer[FIX_SCROLL_JUMP]();
-  });
-
-  let prevRange: typeof range | undefined;
-  onUpdate(() => {
-    if (prevRange && prevRange[0] === range[0] && prevRange[1] === range[1])
-      return;
-    prevRange = range;
-    dispatchEvent("rangeChange", [range[0], range[1]]);
-  });
-
-  /**
-   * Get current scrollTop or scrollLeft.
-   */
-  export const getScrollOffset = virtualizer[GET_SCROLL_OFFSET];
-  /**
-   * Get current scrollHeight or scrollWidth.
-   */
-  export const getScrollSize = virtualizer[GET_SCROLL_SIZE];
-  /**
-   * Get current offsetHeight or offsetWidth.
-   */
-  export const getViewportSize = virtualizer[GET_VIEWPORT_SIZE];
-  /**
-   * Scroll to the item specified by index.
-   * @param index index of item
-   * @param opts options
-   */
-  export const scrollToIndex = virtualizer[SCROLL_TO_INDEX];
-  /**
-   * Scroll to the given offset.
-   * @param offset offset from start
-   */
-  export const scrollTo = virtualizer[SCROLL_TO];
-  /**
-   * Scroll by the given offset.
-   * @param offset offset from current position
-   */
-  export const scrollBy = virtualizer[SCROLL_BY];
-
-  let items: T[];
-  $: {
-    const [startIndex, endIndex] = extendedRange;
-    const newItems: T[] = [];
-    for (let i = startIndex, j = endIndex; i <= j; i++) {
-      newItems.push(data[i]!);
-    }
-    items = newItems;
-  }
+    children,
+    onscroll,
+    onscrollend,
+    onrangechange,
+    ...rest
+  }: Props = $props();
+
+  let ref: Virtualizer<T> = $state()!;
+
+  export const getScrollOffset = (() =>
+    ref.getScrollOffset()) satisfies VListHandle["getScrollOffset"] as VListHandle["getScrollOffset"];
+  export const getScrollSize = (() =>
+    ref.getScrollSize()) satisfies VListHandle["getScrollSize"] as VListHandle["getScrollSize"];
+  export const getViewportSize = (() =>
+    ref.getViewportSize()) satisfies VListHandle["getViewportSize"] as VListHandle["getViewportSize"];
+  export const scrollToIndex = ((...args) =>
+    ref.scrollToIndex(
+      ...args
+    )) satisfies VListHandle["scrollToIndex"] as VListHandle["scrollToIndex"];
+  export const scrollTo = ((...args) =>
+    ref.scrollTo(
+      ...args
+    )) satisfies VListHandle["scrollTo"] as VListHandle["scrollTo"];
+  export const scrollBy = ((...args) =>
+    ref.scrollBy(
+      ...args
+    )) satisfies VListHandle["scrollBy"] as VListHandle["scrollBy"];
 
   const viewportStyle = styleToString({
     display: horizontal ? "inline-block" : "block",
@@ -200,42 +47,24 @@
     width: "100%",
     height: "100%",
   });
-
-  const containerStyle = styleToString({
-    // contain: "content",
-    "overflow-anchor": "none", // opt out browser's scroll anchoring because it will conflict to scroll anchoring of virtualizer
-    flex: "none", // flex style can break layout
-    position: "relative",
-    visibility: "hidden", // TODO replace with other optimization methods
-  });
-
-  $: dynamicContainerStyle = styleToString({
-    width: horizontal ? totalSize + "px" : "100%",
-    height: horizontal ? "100%" : totalSize + "px",
-    "pointer-events": scrollDirection !== SCROLL_IDLE ? "none" : undefined,
-  });
 </script>
 
 <!-- 
   @component
-  Virtualized list component.
+  Virtualized list component. See {@link VListProps} and {@link VListHandle}.
 -->
-<div {...$$restProps} style={`${viewportStyle} ${$$restProps["style"] || ""}`}>
-  <div
-    bind:this={containerRef}
-    style={`${containerStyle} ${dynamicContainerStyle}`}
-  >
-    {#each items as item, i (getKey(item, i + extendedRange[0]))}
-      {@const index = i + extendedRange[0]}
-      <ListItem
-        {index}
-        offset={rerender && virtualizer[GET_ITEM_OFFSET](index)}
-        hide={rerender && virtualizer[IS_ITEM_HIDDEN](index)}
-        {horizontal}
-        resizer={virtualizer[OBSERVE_ITEM_RESIZE]}
-      >
-        <slot {item} {index} />
-      </ListItem>
-    {/each}
-  </div>
+<div {...rest} style={`${viewportStyle} ${rest["style"] || ""}`}>
+  <Virtualizer
+    bind:this={ref}
+    {data}
+    {children}
+    {getKey}
+    {overscan}
+    {itemSize}
+    {shift}
+    {horizontal}
+    {onscroll}
+    {onscrollend}
+    {onrangechange}
+  />
 </div>

package/lib/svelte/VList.svelte.d.ts

@@ -1,92 +1,26 @@
-import { SvelteComponent } from "svelte";
-import type { HTMLAttributes } from "svelte/elements";
+import type { VListProps } from "./VList.type";
 declare class __sveltets_Render<T> {
-    props(): {
-        /**
-           * Get current scrollTop or scrollLeft.
-           */ getScrollOffset?: () => number;
-        /**
-           * Get current scrollHeight or scrollWidth.
-           */ getScrollSize?: () => number;
-        /**
-           * Get current offsetHeight or offsetWidth.
-           */ getViewportSize?: () => number;
-        /**
-           * Scroll to the item specified by index.
-           * @param index index of item
-           * @param opts options
-           */ scrollToIndex?: (index: number, opts?: import("../core/types").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;
-    } & HTMLAttributes<HTMLDivElement> & {
-        /**
-         * The data items rendered by this component.
-         */
-        data: T[];
-        /**
-         * 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) | undefined;
-        /**
-         * Number of items to render above/below the visible bounds of the list. You can increase to avoid showing blank items in fast scrolling.
-         * @defaultValue 4
-         */
-        overscan?: number;
-        /**
-         * Item size hint for unmeasured items. 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;
-        /**
-         * 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.
-         */
-        shift?: boolean;
-        /**
-         * If true, rendered as a horizontally scrollable list. Otherwise rendered as a vertically scrollable list.
-         */
-        horizontal?: boolean;
-    };
-    events(): {
-        /**
-         * Callback invoked whenever scroll offset changes.
-         * @param offset Current scrollTop or scrollLeft.
-         */
-        scroll: CustomEvent<number>;
-        /**
-         * Callback invoked when scrolling stops.
-         */
-        scrollEnd: CustomEvent<void>;
-        /**
-         * Callback invoked when visible items range changes.
-         */
-        rangeChange: CustomEvent<[start: number, end: number]>;
-    };
-    slots(): {
-        default: {
-            item: T;
-            index: number;
-        };
+    props(): VListProps<T>;
+    events(): {};
+    slots(): {};
+    bindings(): "";
+    exports(): {
+        getScrollOffset: () => number;
+        getScrollSize: () => number;
+        getViewportSize: () => number;
+        scrollToIndex: (index: number, opts?: import("../core/types").ScrollToIndexOpts) => void;
+        scrollTo: (offset: number) => void;
+        scrollBy: (offset: number) => void;
     };
 }
-export type VListProps<T> = ReturnType<__sveltets_Render<T>['props']>;
-export type VListEvents<T> = ReturnType<__sveltets_Render<T>['events']>;
-export type VListSlots<T> = ReturnType<__sveltets_Render<T>['slots']>;
-/** Virtualized list component. */
-export default class VList<T> extends SvelteComponent<VListProps<T>, VListEvents<T>, VListSlots<T>> {
-    get getScrollOffset(): () => number;
-    get getScrollSize(): () => number;
-    get getViewportSize(): () => number;
-    get scrollToIndex(): (index: number, opts?: import("../core/types").ScrollToIndexOpts) => void;
-    get scrollTo(): (offset: number) => void;
-    get scrollBy(): (offset: number) => void;
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
 }
-export {};
+/** Virtualized list component. See {@link VListProps} and {@link VListHandle}. */
+declare const VList: $$IsomorphicComponent;
+type VList<T> = InstanceType<typeof VList<T>>;
+export default VList;

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

@@ -0,0 +1,13 @@
+// @ts-nocheck
+import type { ViewportComponentAttributes } from "./types";
+import type { VirtualizerHandle, VirtualizerProps } from "./Virtualizer.type";
+/**
+ * Props of {@link VList}.
+ */
+export interface VListProps<T> extends Pick<VirtualizerProps<T>, "data" | "getKey" | "overscan" | "itemSize" | "shift" | "horizontal" | "children" | "onscroll" | "onscrollend" | "onrangechange">, ViewportComponentAttributes {
+}
+/**
+ * Methods of {@link VList}.
+ */
+export interface VListHandle extends VirtualizerHandle {
+}

package/lib/svelte/VList.type.js

@@ -0,0 +1 @@
+export {};