virtua 0.49.3 → 0.50.0

package/README.md

@@ -2,7 +2,7 @@
 
 ![npm](https://img.shields.io/npm/v/virtua) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/virtua) ![npm](https://img.shields.io/npm/dw/virtua) [![Best of JS](https://img.shields.io/endpoint?url=https://bestofjs-serverless.now.sh/api/project-badge?fullName=inokawa%2Fvirtua%26since=daily)](https://bestofjs.org/projects/virtua) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/inokawa/virtua) [![check](https://github.com/inokawa/virtua/actions/workflows/check.yml/badge.svg)](https://github.com/inokawa/virtua/actions/workflows/check.yml) [![demo](https://github.com/inokawa/virtua/actions/workflows/demo.yml/badge.svg)](https://github.com/inokawa/virtua/actions/workflows/demo.yml)
 
-> A zero-config, fast and small (~3kB) virtual list (and grid) component for [React](https://github.com/facebook/react), [Vue](https://vuejs.org/), [Solid](https://www.solidjs.com/) and [Svelte](https://svelte.dev/).
+> A zero-config, fast and small (~3kB) virtual list (and grid) component for [React](https://github.com/facebook/react), [Vue](https://vuejs.org/), [Solid](https://www.solidjs.com/), [Svelte](https://svelte.dev/) and [Angular](https://angular.dev/).
 
 ![example](./example.gif)
 
@@ -16,7 +16,7 @@ This project is a challenge to rethink virtualization. The goals are...
 - **Fast:** Natural virtual scrolling needs optimization in many aspects (eliminate frame drops by reducing CPU usage and GC, reduce [synchronous layout recalculation](https://gist.github.com/paulirish/5d52fb081b3570c81e3a), reduce visual jumps on repaint, optimize with CSS, optimize for JIT, optimize for frameworks, etc). We are trying to combine the best of them.
 - **Small:** Its bundle size should be small as much as possible to be friendly with modern web development. Currently each components are ~3kB gzipped and tree-shakeable.
 - **Flexible:** Aiming to support many usecases - fixed size, dynamic size, horizontal scrolling, reverse scrolling, RTL, mobile, infinite scrolling, scroll restoration, DnD, keyboard navigation, sticky, placeholder and more. See [live demo](#demo).
-- **Framework agnostic:** [React](https://react.dev/), [Vue](https://vuejs.org/), [Solid](https://www.solidjs.com/) and [Svelte](https://svelte.dev/) are supported. We could support other frameworks in the future.
+- **Framework agnostic:** [React](https://react.dev/), [Vue](https://vuejs.org/), [Solid](https://www.solidjs.com/), [Svelte](https://svelte.dev/) and [Angular](https://angular.dev/) are supported. We could support other frameworks in the future.
 
 ## Demo
 
@@ -261,7 +261,7 @@ export const App = () => {
 
   const sizes = [20, 40, 180, 77];
 
-  const data = Array.from({ length: 1000 }).map((_, i) => sizes[i % 4] );
+  const data = Array.from({ length: 1000 }).map((_, i) => sizes[i % 4]);
 </script>
 
 <VList {data} style="height: 100vh;" getKey={(_, i) => i}>
@@ -279,6 +279,40 @@ export const App = () => {
 </VList>
 ```
 
+### Angular
+
+`@angular/core >= 20` is required. The components are zoneless-ready and work with both zone.js and [`provideZonelessChangeDetection`](https://angular.dev/api/core/provideZonelessChangeDetection).
+
+```ts
+import { Component } from "@angular/core";
+import { VList } from "virtua/angular";
+
+const sizes = [20, 40, 180, 77];
+
+@Component({
+  selector: "app-root",
+  imports: [VList],
+  template: `
+    <virtua-vlist [data]="data" [getKey]="getKey" style="height: 800px;">
+      <ng-template let-item let-index="index">
+        <div
+          [style.height.px]="item"
+          style="background: white; border-bottom: solid 1px #ccc;"
+        >
+          {{ index }}
+        </div>
+      </ng-template>
+    </virtua-vlist>
+  `,
+})
+export class App {
+  protected readonly data = Array.from({ length: 1000 }).map(
+    (_, i) => sizes[i % 4]!,
+  );
+  protected readonly getKey = (_: number, i: number) => i;
+}
+```
+
 ### Other bindings
 
 - [vanilla-virtua](https://github.com/aabccd021/vanilla-virtua): virtua for vanilla js
@@ -356,9 +390,9 @@ And do not use index of items as `key`, especially when you want to toggle `shif
 
 `viewportSize` will be calculated by ResizeObserver so it's 0 until the first measurement.
 
-#### What is `Cannot find module 'virtua/vue(solid|svelte)' or its corresponding type declarations` error?
+#### What is `Cannot find module 'virtua/vue(solid|svelte|angular)' or its corresponding type declarations` error?
 
-This package uses [exports of package.json](https://nodejs.org/api/packages.html#package-entry-points) for entry point of Vue/Solid/Svelte adapter. This field can't be resolved in TypeScript with `moduleResolution: node`. Try `moduleResolution: bundler` or `moduleResolution: nodenext` instead.
+This package uses [exports of package.json](https://nodejs.org/api/packages.html#package-entry-points) for entry point of Vue/Solid/Svelte/Angular adapter. This field can't be resolved in TypeScript with `moduleResolution: node`. Try `moduleResolution: bundler` or `moduleResolution: nodenext` instead.
 
 ## Comparison
 

package/lib/angular/ListItem.d.ts

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

package/lib/angular/VList.d.ts

@@ -0,0 +1,85 @@
+import { type OnInit } from "@angular/core";
+import { type CacheSnapshot, type ScrollToIndexOpts } from "../core/index.js";
+import { type VirtualizerHandle } from "./Virtualizer.js";
+import { type ItemProps } from "./utils.js";
+import * as i0 from "@angular/core";
+/**
+ * Methods of {@link VList}.
+ */
+export interface VListHandle extends VirtualizerHandle {
+}
+/**
+ * Virtualized list component. See {@link VListHandle}.
+ *
+ * The host element is the scrollable viewport of the list.
+ */
+export declare class VList<T> implements OnInit, VListHandle {
+    /**
+     * The data items rendered by this component.
+     */
+    readonly data: import("@angular/core").InputSignal<readonly 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)
+     */
+    readonly getKey: import("@angular/core").InputSignal<(data: T, index: number) => string | number>;
+    /**
+     * A function that provides properties/attributes for item element
+     */
+    readonly itemProps: import("@angular/core").InputSignal<ItemProps<T> | undefined>;
+    /**
+     * 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
+     */
+    readonly bufferSize: import("@angular/core").InputSignal<number | undefined>;
+    /**
+     * 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.
+     */
+    readonly itemSize: import("@angular/core").InputSignal<number | undefined>;
+    /**
+     * A prop for SSR. If set, the specified amount of items will be mounted in the initial rendering regardless of the container size until hydrated. The minimum value is 0.
+     */
+    readonly ssrCount: import("@angular/core").InputSignal<number | undefined>;
+    /**
+     * 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.
+     */
+    readonly shift: import("@angular/core").InputSignal<boolean>;
+    /**
+     * If true, rendered as a horizontally scrollable list. Otherwise rendered as a vertically scrollable list.
+     */
+    readonly horizontal: import("@angular/core").InputSignal<boolean>;
+    /**
+     * List of indexes that should be always mounted, even when off screen.
+     */
+    readonly keepMounted: import("@angular/core").InputSignal<readonly number[] | undefined>;
+    /**
+     * 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 VListHandle.getCache}.
+     *
+     * **The length of items should be the same as when you take the snapshot, otherwise restoration may not work as expected.**
+     */
+    readonly cache: import("@angular/core").InputSignal<CacheSnapshot | undefined>;
+    /**
+     * Emitted whenever scroll offset changes. The value is current scrollTop, or scrollLeft if horizontal: true.
+     */
+    readonly scroll: import("@angular/core").OutputEmitterRef<number>;
+    /**
+     * Emitted when scrolling stops.
+     */
+    readonly scrollEnd: import("@angular/core").OutputEmitterRef<void>;
+    ngOnInit(): void;
+    getCache(): CacheSnapshot;
+    getScrollOffset(): number;
+    getScrollSize(): number;
+    getViewportSize(): number;
+    findItemIndex(offset: number): number;
+    getItemOffset(index: number): number;
+    getItemSize(index: number): number;
+    scrollToIndex(index: number, opts?: ScrollToIndexOpts): void;
+    scrollTo(offset: number): void;
+    scrollBy(offset: number): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<VList<any>, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<VList<any>, "virtua-vlist", never, { "data": { "alias": "data"; "required": true; "isSignal": true; }; "getKey": { "alias": "getKey"; "required": false; "isSignal": true; }; "itemProps": { "alias": "itemProps"; "required": false; "isSignal": true; }; "bufferSize": { "alias": "bufferSize"; "required": false; "isSignal": true; }; "itemSize": { "alias": "itemSize"; "required": false; "isSignal": true; }; "ssrCount": { "alias": "ssrCount"; "required": false; "isSignal": true; }; "shift": { "alias": "shift"; "required": false; "isSignal": true; }; "horizontal": { "alias": "horizontal"; "required": false; "isSignal": true; }; "keepMounted": { "alias": "keepMounted"; "required": false; "isSignal": true; }; "cache": { "alias": "cache"; "required": false; "isSignal": true; }; }, { "scroll": "scroll"; "scrollEnd": "scrollEnd"; }, ["template"], never, true, never>;
+}

package/lib/angular/Virtualizer.d.ts

@@ -0,0 +1,141 @@
+import { type OnInit } from "@angular/core";
+import { type CacheSnapshot, type ScrollToIndexOpts } from "../core/index.js";
+import { type ItemProps } from "./utils.js";
+import * as i0 from "@angular/core";
+/**
+ * Methods of {@link Virtualizer}.
+ */
+export interface VirtualizerHandle {
+    /**
+     * Get current {@link CacheSnapshot}.
+     */
+    getCache: () => CacheSnapshot;
+    /**
+     * Get current scrollTop, or scrollLeft if horizontal: true.
+     */
+    getScrollOffset: () => number;
+    /**
+     * Get current scrollHeight, or scrollWidth if horizontal: true.
+     */
+    getScrollSize: () => number;
+    /**
+     * Get current offsetHeight, or offsetWidth if horizontal: true.
+     */
+    getViewportSize: () => number;
+    /**
+     * Find nearest item index from offset.
+     * @param offset offset in pixels from the start of the scroll container
+     */
+    findItemIndex(offset: number): 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;
+}
+/**
+ * Customizable list virtualizer for advanced usage. See {@link VirtualizerHandle}.
+ *
+ * The host element is the container of the items. Use the attribute selector to change its tag,
+ * like `<ul virtuaVirtualizer [data]="data">`.
+ */
+export declare class Virtualizer<T> implements OnInit, VirtualizerHandle {
+    /**
+     * The data items rendered by this component.
+     */
+    readonly data: import("@angular/core").InputSignal<readonly 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)
+     */
+    readonly getKey: import("@angular/core").InputSignal<(data: T, index: number) => string | number>;
+    /**
+     * A function that provides properties/attributes for item element
+     */
+    readonly itemProps: import("@angular/core").InputSignal<ItemProps<T> | undefined>;
+    /**
+     * 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
+     */
+    readonly bufferSize: import("@angular/core").InputSignal<number | undefined>;
+    /**
+     * Reference to the scrollable element. The default will get the direct parent element of virtualizer.
+     */
+    readonly scrollRef: import("@angular/core").InputSignal<HTMLElement | undefined>;
+    /**
+     * 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.
+     */
+    readonly itemSize: import("@angular/core").InputSignal<number | undefined>;
+    /**
+     * A prop for SSR. If set, the specified amount of items will be mounted in the initial rendering regardless of the container size until hydrated. The minimum value is 0.
+     */
+    readonly ssrCount: import("@angular/core").InputSignal<number | undefined>;
+    /**
+     * 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.
+     */
+    readonly shift: import("@angular/core").InputSignal<boolean>;
+    /**
+     * If true, rendered as a horizontally scrollable list. Otherwise rendered as a vertically scrollable list.
+     */
+    readonly horizontal: import("@angular/core").InputSignal<boolean>;
+    /**
+     * List of indexes that should be always mounted, even when off screen.
+     */
+    readonly keepMounted: import("@angular/core").InputSignal<readonly number[] | undefined>;
+    /**
+     * 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 VirtualizerHandle.getCache}.
+     *
+     * **The length of items should be the same as when you take the snapshot, otherwise restoration may not work as expected.**
+     */
+    readonly cache: import("@angular/core").InputSignal<CacheSnapshot | undefined>;
+    /**
+     * The offset to the scrollable parent before virtualizer in pixels. If you put an element before virtualizer, you have to set its height to this prop.
+     */
+    readonly startMargin: import("@angular/core").InputSignal<number>;
+    /**
+     * Emitted whenever scroll offset changes. The value is current scrollTop, or scrollLeft if horizontal: true.
+     */
+    readonly scroll: import("@angular/core").OutputEmitterRef<number>;
+    /**
+     * Emitted when scrolling stops.
+     */
+    readonly scrollEnd: import("@angular/core").OutputEmitterRef<void>;
+    constructor();
+    ngOnInit(): void;
+    getCache(): CacheSnapshot;
+    getScrollOffset(): number;
+    getScrollSize(): number;
+    getViewportSize(): number;
+    findItemIndex(offset: number): number;
+    getItemOffset(index: number): number;
+    getItemSize(index: number): number;
+    scrollToIndex(index: number, opts?: ScrollToIndexOpts): void;
+    scrollTo(offset: number): void;
+    scrollBy(offset: number): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<Virtualizer<any>, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<Virtualizer<any>, "virtua-virtualizer, [virtuaVirtualizer]", never, { "data": { "alias": "data"; "required": true; "isSignal": true; }; "getKey": { "alias": "getKey"; "required": false; "isSignal": true; }; "itemProps": { "alias": "itemProps"; "required": false; "isSignal": true; }; "bufferSize": { "alias": "bufferSize"; "required": false; "isSignal": true; }; "scrollRef": { "alias": "scrollRef"; "required": false; "isSignal": true; }; "itemSize": { "alias": "itemSize"; "required": false; "isSignal": true; }; "ssrCount": { "alias": "ssrCount"; "required": false; "isSignal": true; }; "shift": { "alias": "shift"; "required": false; "isSignal": true; }; "horizontal": { "alias": "horizontal"; "required": false; "isSignal": true; }; "keepMounted": { "alias": "keepMounted"; "required": false; "isSignal": true; }; "cache": { "alias": "cache"; "required": false; "isSignal": true; }; "startMargin": { "alias": "startMargin"; "required": false; "isSignal": true; }; "itemTemplate": { "alias": "itemTemplate"; "required": false; "isSignal": true; }; }, { "scroll": "scroll"; "scrollEnd": "scrollEnd"; }, ["contentTemplate"], never, true, never>;
+}

package/lib/angular/WindowVirtualizer.d.ts

@@ -0,0 +1,103 @@
+import { type OnInit } from "@angular/core";
+import { type CacheSnapshot, type ScrollToIndexOpts } from "../core/index.js";
+import * as i0 from "@angular/core";
+/**
+ * Methods of {@link WindowVirtualizer}.
+ */
+export interface WindowVirtualizerHandle {
+    /**
+     * Get current {@link CacheSnapshot}.
+     */
+    getCache: () => CacheSnapshot;
+    /**
+     * Get current scrollTop, or scrollLeft if horizontal: true.
+     */
+    getScrollOffset: () => number;
+    /**
+     * Get current offsetHeight, or offsetWidth if horizontal: true.
+     */
+    getViewportSize: () => number;
+    /**
+     * Find nearest item index from offset.
+     * @param offset offset in pixels from the start of the scroll container
+     */
+    findItemIndex(offset: number): 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;
+}
+/**
+ * {@link Virtualizer} controlled by the window scrolling. See {@link WindowVirtualizerHandle}.
+ *
+ * The host element is the container of the items. Use the attribute selector to change its tag,
+ * like `<ul virtuaWindowVirtualizer [data]="data">`.
+ */
+export declare class WindowVirtualizer<T> implements OnInit, WindowVirtualizerHandle {
+    /**
+     * The data items rendered by this component.
+     */
+    readonly data: import("@angular/core").InputSignal<readonly 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)
+     */
+    readonly getKey: import("@angular/core").InputSignal<(data: T, index: number) => string | 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
+     */
+    readonly bufferSize: import("@angular/core").InputSignal<number | undefined>;
+    /**
+     * 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.
+     */
+    readonly itemSize: import("@angular/core").InputSignal<number | undefined>;
+    /**
+     * 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.
+     */
+    readonly shift: import("@angular/core").InputSignal<boolean>;
+    /**
+     * If true, rendered as a horizontally scrollable list. Otherwise rendered as a vertically scrollable list.
+     */
+    readonly horizontal: import("@angular/core").InputSignal<boolean>;
+    /**
+     * 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 WindowVirtualizerHandle.getCache}.
+     *
+     * **The length of items should be the same as when you take the snapshot, otherwise restoration may not work as expected.**
+     */
+    readonly cache: import("@angular/core").InputSignal<CacheSnapshot | undefined>;
+    /**
+     * Emitted whenever scroll offset changes.
+     */
+    readonly scroll: import("@angular/core").OutputEmitterRef<void>;
+    /**
+     * Emitted when scrolling stops.
+     */
+    readonly scrollEnd: import("@angular/core").OutputEmitterRef<void>;
+    constructor();
+    ngOnInit(): void;
+    getCache(): CacheSnapshot;
+    getScrollOffset(): number;
+    getViewportSize(): number;
+    findItemIndex(offset: number): number;
+    getItemOffset(index: number): number;
+    getItemSize(index: number): number;
+    scrollToIndex(index: number, opts?: ScrollToIndexOpts): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<WindowVirtualizer<any>, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<WindowVirtualizer<any>, "virtua-window-virtualizer, [virtuaWindowVirtualizer]", never, { "data": { "alias": "data"; "required": true; "isSignal": true; }; "getKey": { "alias": "getKey"; "required": false; "isSignal": true; }; "bufferSize": { "alias": "bufferSize"; "required": false; "isSignal": true; }; "itemSize": { "alias": "itemSize"; "required": false; "isSignal": true; }; "shift": { "alias": "shift"; "required": false; "isSignal": true; }; "horizontal": { "alias": "horizontal"; "required": false; "isSignal": true; }; "cache": { "alias": "cache"; "required": false; "isSignal": true; }; }, { "scroll": "scroll"; "scrollEnd": "scrollEnd"; }, ["template"], never, true, never>;
+}

package/lib/angular/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @module angular
+ */
+export { VList, type VListHandle } from "./VList.js";
+export { Virtualizer, type VirtualizerHandle } from "./Virtualizer.js";
+export { WindowVirtualizer, type WindowVirtualizerHandle, } from "./WindowVirtualizer.js";