Rename element props to components

src/index.ts

@@ -1,21 +1,2 @@
 export type { CacheSnapshot } from "./core/types";
-export { VList } from "./react/VList";
-export type { VListProps, VListHandle, ScrollMode } from "./react/VList";
-export { VGrid } from "./react/VGrid";
-export type {
-  VGridProps,
-  VGridHandle,
-  CustomCellComponent,
-  CustomCellComponentProps,
-} from "./react/VGrid";
-export { WVList } from "./react/WVList";
-export type { WVListProps, WVListHandle } from "./react/WVList";
-export type {
-  WindowComponentAttributes,
-  CustomWindowComponent,
-  CustomWindowComponentProps,
-} from "./react/Window";
-export type {
-  CustomItemComponent,
-  CustomItemComponentProps,
-} from "./react/ListItem";
+export * from "./react";

src/react/VGrid.spec.tsx

@@ -104,7 +104,7 @@ it("should pass attributes to element", async () => {
 });
 
 // it("should change components", async () => {
-//   const UlList = forwardRef<HTMLDivElement, CustomWindowComponentProps>(
+//   const UlList = forwardRef<HTMLDivElement, CustomViewportComponentProps>(
 //     ({ children, attrs, scrollSize }, ref) => {
 //       return (
 //         <div ref={ref} {...attrs}>
@@ -116,7 +116,7 @@ it("should pass attributes to element", async () => {
 //     }
 //   );
 //   const { asFragment } = render(
-//     <VList element={UlList} itemElement="li">
+//     <VList components={{ Root: UlList, Item: "li" }}>
 //       <div>0</div>
 //       <div>1</div>
 //       <div>2</div>

src/react/VGrid.tsx

@@ -20,15 +20,15 @@
 } from "./useSelector";
 import { max, min, values } from "../core/utils";
 import { createScroller } from "../core/scroller";
-import { refKey } from "./utils";
+import { emptyComponents, refKey } from "./utils";
 import { useStatic } from "./useStatic";
 import {
-  CustomWindowComponent,
-  CustomWindowComponentProps,
-  WindowComponentAttributes,
+  CustomViewportComponent,
+  CustomViewportComponentProps,
+  ViewportComponentAttributes,
 } from "..";
 import { createGridResizer, GridResizer } from "../core/resizer";
-import { Window as DefaultWindow } from "./Window";
+import { Viewport as DefaultViewport } from "./Viewport";
 
 const genKey = (i: number, j: number) => `${i}-${j}`;
 
@@ -131,7 +131,7 @@
             minWidth: width,
           };
           return style;
         }, [top, left, width, height, vHide, hHide])}
       >
         {children}
       </Element>
@@ -178,7 +178,7 @@
 /**
  * Props of {@link VGrid}.
  */
-export interface VGridProps extends WindowComponentAttributes {
+export interface VGridProps extends ViewportComponentAttributes {
   /**
    * A function to create elements rendered by this component.
    */
@@ -228,15 +228,20 @@
    */
   rtl?: boolean;
   /**
-   * Customized element type for scrollable element. This element will get {@link CustomWindowComponentProps} as props.
-   * @defaultValue {@link Window}
+   * Customized components for advanced usage.
    */
-  element?: CustomWindowComponent;
-  /**
-   * Customized element type for cell element. This element will get {@link CustomCellComponentProps} as props.
-   * @defaultValue "div"
-   */
-  cellElement?: CustomCellComponentOrElement;
+  components?: {
+    /**
+     * Component for scrollable element. This component will get {@link CustomViewportComponentProps} as props.
+     * @defaultValue {@link DefaultViewport}
+     */
+    Root?: CustomViewportComponent;
+    /**
+     * Component or element type for cell element. This component will get {@link CustomCellComponentProps} as props.
+     * @defaultValue "div"
+     */
+    Cell?: CustomCellComponentOrElement;
+  };
 }
 
 /**
@@ -254,9 +259,14 @@
       initialRowCount,
       initialColCount,
       rtl: rtlProp,
-      element: Window = DefaultWindow,
-      cellElement: itemElement = "div",
-      ...windowAttrs
+      components: {
+        Root: Viewport = DefaultViewport,
+        Cell: ItemElement = "div",
+      } = emptyComponents as {
+        Root?: CustomViewportComponent;
+        Cell?: CustomCellComponentOrElement;
+      },
+      ...viewportAttrs
     },
     ref
   ): ReactElement => {
@@ -388,7 +398,7 @@
           },
         };
       },
       []
     );
 
     const render = useMemo(() => {
@@ -421,7 +431,7 @@
               _hStore={hStore}
               _rowIndex={i}
               _colIndex={j}
-              _element={itemElement as "div"}
+              _element={ItemElement as "div"}
               _children={render(i, j)}
               _isRtl={isRtl}
             />
@@ -430,7 +440,7 @@
       }
 
       return res;
     }, [
       render,
       overscanedStartRowIndex,
       overscanedEndRowIndex,
@@ -439,14 +449,14 @@
     ]);
 
     return (
-      <Window
+      <Viewport
         ref={rootRef}
         width={width}
         height={height}
         scrolling={verticalScrolling || horizontalScrolling}
         attrs={useMemo(
           () => ({
-            ...windowAttrs,
+            ...viewportAttrs,
             style: {
               overflow: "auto",
               contain: "strict",
@@ -457,14 +467,14 @@
               height: "100%",
               padding: 0,
               margin: 0,
-              ...windowAttrs.style,
+              ...viewportAttrs.style,
             },
           }),
-          values(windowAttrs)
+          values(viewportAttrs)
         )}
       >
         {items}
-      </Window>
+      </Viewport>
     );
   }
 );

src/react/VList.spec.tsx

@@ -9,7 +9,7 @@ import {
   useRef,
   useState,
 } from "react";
-import { CustomWindowComponentProps } from "..";
+import { CustomViewportComponentProps } from "..";
 
 const ITEM_HEIGHT = 50;
 const ITEM_WIDTH = 100;
@@ -107,7 +107,7 @@ it("should pass attributes to element", async () => {
 });
 
 it("should change components", async () => {
-  const UlList = forwardRef<HTMLDivElement, CustomWindowComponentProps>(
+  const UlList = forwardRef<HTMLDivElement, CustomViewportComponentProps>(
     ({ children, attrs, height }, ref) => {
       return (
         <div ref={ref} {...attrs}>
@@ -119,7 +119,7 @@ it("should change components", async () => {
     }
   );
   const { asFragment } = render(
-    <VList element={UlList} itemElement="li">
+    <VList components={{ Root: UlList, Item: "li" }}>
       <div>0</div>
       <div>1</div>
       <div>2</div>

src/react/VList.tsx

@@ -18,16 +18,16 @@
 } from "./useSelector";
 import { exists, max, min, values } from "../core/utils";
 import { createScroller } from "../core/scroller";
-import { MayHaveKey, flattenChildren, refKey } from "./utils";
+import { MayHaveKey, emptyComponents, flattenChildren, refKey } from "./utils";
 import { useStatic } from "./useStatic";
 import { useRefWithUpdate } from "./useRefWithUpdate";
 import { createResizer } from "../core/resizer";
-import { WindowComponentAttributes } from "..";
+import { ViewportComponentAttributes } from "..";
 import {
-  CustomWindowComponent,
-  CustomWindowComponentProps,
-  Window as DefaultWindow,
-} from "./Window";
+  CustomViewportComponent,
+  CustomViewportComponentProps,
+  Viewport as DefaultViewport,
+} from "./Viewport";
 import { CustomItemComponent, ListItem } from "./ListItem";
 import { CacheSnapshot } from "../core/types";
 
@@ -77,7 +77,7 @@
 /**
  * Props of {@link VList}.
  */
-export interface VListProps extends WindowComponentAttributes {
+export interface VListProps extends ViewportComponentAttributes {
   /**
    * Elements rendered by this component.
    */
@@ -114,15 +114,20 @@
    */
   cache?: CacheSnapshot;
   /**
-   * Customized element type for scrollable element. This element will get {@link CustomWindowComponentProps} as props.
-   * @defaultValue {@link Window}
+   * Customized components for advanced usage.
    */
-  element?: CustomWindowComponent;
-  /**
-   * Customized element type for item element. This element will get {@link CustomItemComponentProps} as props.
-   * @defaultValue "div"
-   */
-  itemElement?: CustomItemComponentOrElement;
+  components?: {
+    /**
+     * Component for scrollable element. This component will get {@link CustomViewportComponentProps} as props.
+     * @defaultValue {@link DefaultViewport}
+     */
+    Root?: CustomViewportComponent;
+    /**
+     * Component or element type for item element. This component will get {@link CustomItemComponentProps} as props.
+     * @defaultValue "div"
+     */
+    Item?: CustomItemComponentOrElement;
+  };
   /**
    * Callback invoked whenever scroll offset changes.
    * @param offset Current scrollTop or scrollLeft.
@@ -160,12 +165,17 @@
       horizontal: horizontalProp,
       mode,
       cache,
-      element: Window = DefaultWindow,
-      itemElement = "div",
+      components: {
+        Root: Viewport = DefaultViewport,
+        Item: ItemElement = "div",
+      } = emptyComponents as {
+        Root?: CustomViewportComponent;
+        Item?: CustomItemComponentOrElement;
+      },
       onScroll: onScrollProp,
       onScrollStop: onScrollStopProp,
       onRangeChange: onRangeChangeProp,
-      ...windowAttrs
+      ...viewportAttrs
     },
     ref
   ): ReactElement => {
@@ -245,13 +255,13 @@
       if (!scrolling) {
         onScrollStop[refKey] && onScrollStop[refKey]();
       }
     }, [scrolling]);
 
     useEffect(() => {
       if (!onRangeChangeProp) return;
 
       onRangeChangeProp(startIndex, endIndex);
     }, [startIndex, endIndex]);
 
     useImperativeHandle(
       ref,
@@ -276,7 +286,7 @@
           },
         };
       },
       []
     );
 
     const overscanedStartIndex = max(startIndex - overscan, 0);
@@ -293,7 +303,7 @@
               _resizer={resizer}
               _store={store}
               _index={i}
-              _element={itemElement as "div"}
+              _element={ItemElement as "div"}
               _children={e}
               _isHorizontal={isHorizontal}
               _isRtl={isRtl}
@@ -302,17 +312,17 @@
         }
       }
       return res;
     }, [elements, overscanedStartIndex, overscanedEndIndex]);
 
     return (
-      <Window
+      <Viewport
         ref={rootRef}
         width={isHorizontal ? scrollSize : undefined}
         height={isHorizontal ? undefined : scrollSize}
         scrolling={scrolling}
         attrs={useMemo(
           () => ({
-            ...windowAttrs,
+            ...viewportAttrs,
             style: {
               overflow: isHorizontal ? "auto hidden" : "hidden auto",
               display: isHorizontal ? "inline-block" : "block",
@@ -326,14 +336,14 @@
               height: "100%",
               padding: 0,
               margin: 0,
-              ...windowAttrs.style,
+              ...viewportAttrs.style,
             },
           }),
-          values(windowAttrs)
+          values(viewportAttrs)
         )}
       >
         {items}
-      </Window>
+      </Viewport>
     );
   }
 );

src/react/Window.tsx → src/react/Viewport.tsx

@@ -6,7 +6,7 @@ import {
   useMemo,
 } from "react";
 
-export type WindowComponentAttributes = Pick<
+export type ViewportComponentAttributes = Pick<
   React.HTMLAttributes<HTMLElement>,
   "className" | "style" | "id" | "role" | "tabIndex"
 > &
@@ -15,15 +15,15 @@ export type WindowComponentAttributes = Pick<
 /**
  * Props of customized scrollable component.
  */
-export interface CustomWindowComponentProps {
+export interface CustomViewportComponentProps {
   /**
    * Renderable item elements.
    */
   children: ReactNode;
   /**
    * Attributes that should be passed to the scrollable element.
    */
-  attrs: WindowComponentAttributes;
+  attrs: ViewportComponentAttributes;
   /**
    * Total height of items. It's undefined if component is not vertically scrollable.
    */
@@ -38,7 +38,7 @@ export interface CustomWindowComponentProps {
   scrolling: boolean;
 }
 
-export const Window = forwardRef<any, CustomWindowComponentProps>(
+export const Viewport = forwardRef<any, CustomViewportComponentProps>(
   ({ children, attrs, width, height, scrolling }, ref): ReactElement => {
     return (
       <div ref={ref} {...attrs}>
@@ -60,4 +60,4 @@ export const Window = forwardRef<any, CustomWindowComponentProps>(
   }
 );
 
-export type CustomWindowComponent = typeof Window;
+export type CustomViewportComponent = typeof Viewport;

src/react/WVList.spec.tsx

@@ -2,7 +2,7 @@ import { afterEach, it, expect, describe, jest } from "@jest/globals";
 import { render, cleanup } from "@testing-library/react";
 import { WVList } from "./WVList";
 import { Profiler, ReactElement, forwardRef, useEffect, useState } from "react";
-import { CustomWindowComponentProps } from "..";
+import { CustomViewportComponentProps } from "..";
 
 const ITEM_HEIGHT = 50;
 const ITEM_WIDTH = 100;
@@ -77,7 +77,7 @@ it("should pass attributes to element", async () => {
 });
 
 it("should change components", async () => {
-  const UlList = forwardRef<HTMLDivElement, CustomWindowComponentProps>(
+  const UlList = forwardRef<HTMLDivElement, CustomViewportComponentProps>(
     ({ children, attrs, height }, ref) => {
       return (
         <div ref={ref} {...attrs}>
@@ -89,7 +89,7 @@ it("should change components", async () => {
     }
   );
   const { asFragment } = render(
-    <WVList element={UlList} itemElement="li">
+    <WVList components={{ Root: UlList, Item: "li" }}>
       <div>0</div>
       <div>1</div>
       <div>2</div>