vlist-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Floor IO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# vlist-react
+
+React hooks for [vlist](https://github.com/floor/vlist) - lightweight, zero-dependency virtual scrolling.
+
+## Installation
+
+```bash
+npm install @floor/vlist vlist-react
+```
+
+## Usage
+
+```tsx
+import { useVList } from 'vlist-react';
+import '@floor/vlist/styles';
+
+function UserList({ users }) {
+  const { containerRef, instanceRef } = useVList({
+    item: {
+      height: 48,
+      template: (user) => `<div class="user">${user.name}</div>`,
+    },
+    items: users,
+  });
+
+  return <div ref={containerRef} style={{ height: 400 }} />;
+}
+```
+
+## API
+
+### `useVList(config)`
+
+**Parameters:**
+- `config` - VList configuration (same as core vlist, minus `container`)
+
+**Returns:**
+- `containerRef` - Ref to attach to your container element
+- `instanceRef` - Reference to the vlist instance
+- `getInstance()` - Helper function to get the instance
+
+## Documentation
+
+For full documentation, see [vlist.dev](https://vlist.dev)
+
+## License
+
+MIT © [Floor IO](https://floor.io)

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * React hooks for vlist - lightweight virtual scrolling
+ *
+ * @packageDocumentation
+ */
+import type { VListConfig, VListItem, VList, VListEvents, EventHandler } from "@floor/vlist";
+/** Configuration for useVList (VListConfig without container) */
+export type UseVListConfig<T extends VListItem = VListItem> = Omit<VListConfig<T>, "container">;
+/** Return value from the useVList hook */
+export interface UseVListReturn<T extends VListItem = VListItem> {
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    instanceRef: React.RefObject<VList<T> | null>;
+    getInstance: () => VList<T> | null;
+}
+/**
+ * React hook for vlist integration.
+ *
+ * @example
+ * ```tsx
+ * import { useVList } from 'vlist-react';
+ * import '@floor/vlist/styles';
+ *
+ * function UserList({ users }) {
+ *   const { containerRef, instanceRef } = useVList({
+ *     item: {
+ *       height: 48,
+ *       template: (user) => `<div>${user.name}</div>`,
+ *     },
+ *     items: users,
+ *   });
+ *
+ *   return <div ref={containerRef} style={{ height: 400 }} />;
+ * }
+ * ```
+ */
+export declare function useVList<T extends VListItem = VListItem>(config: UseVListConfig<T>): UseVListReturn<T>;
+/**
+ * Subscribe to vlist events within React lifecycle
+ *
+ * @example
+ * ```tsx
+ * useVListEvent(instanceRef, 'selection:change', ({ selected }) => {
+ *   console.log('Selected:', selected);
+ * });
+ * ```
+ */
+export declare function useVListEvent<T extends VListItem, K extends keyof VListEvents<T>>(instanceRef: React.RefObject<VList<T> | null>, event: K, handler: EventHandler<VListEvents<T>[K]>): void;

package/dist/index.js

@@ -0,0 +1 @@
+import{useRef as J,useEffect as Q,useCallback as X}from"react";import{vlist as Y}from"@floor/vlist";import{withAsync as Z,withGrid as _,withSections as $,withSelection as U,withScrollbar as k,withScale as A,withSnapshots as G,withPage as H}from"@floor/vlist";function V(B){let F=J(null),z=J(null),q=J(B);q.current=B;let D=J(!1);Q(()=>{let M=F.current;if(!M)return;let j=Y({...q.current,container:M});if(q.current.scroll?.element===window)j=j.use(H());if(q.current.adapter)j=j.use(Z({adapter:q.current.adapter,...q.current.loading&&{loading:q.current.loading}}));if(q.current.layout==="grid"&&q.current.grid)j=j.use(_(q.current.grid));if(q.current.groups)j=j.use($(q.current.groups));if((q.current.selection?.mode||"none")!=="none")j=j.use(U(q.current.selection));else j=j.use(U({mode:"none"}));j=j.use(A());let N=q.current.scroll?.scrollbar||q.current.scrollbar;if(N!=="none"){let W=typeof N==="object"?N:{};j=j.use(k(W))}j=j.use(G());let T=j.build();return z.current=T,D.current=!0,()=>{D.current=!1,T.destroy(),z.current=null}},[]),Q(()=>{if(!D.current||!z.current)return;if(B.items)z.current.setItems(B.items)},[B.items]);let K=X(()=>{return z.current},[]);return{containerRef:F,instanceRef:z,getInstance:K}}function x(B,F,z){let q=J(z);q.current=z,Q(()=>{let D=B.current;if(!D)return;let K=(j)=>{q.current(j)};return D.on(F,K)},[B.current,F])}export{x as useVListEvent,V as useVList};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "vlist-react",
+  "version": "0.1.0",
+  "description": "React hooks for vlist - lightweight virtual scrolling",
+  "author": {
+    "name": "Floor IO",
+    "url": "https://floor.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/floor/vlist-react.git"
+  },
+  "keywords": [
+    "vlist",
+    "virtual-list",
+    "react",
+    "hooks",
+    "virtual-scrolling",
+    "typescript"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@floor/vlist": "^0.6.0",
+    "react": ">=17.0.0"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/**/*.d.ts.map"
+  ],
+  "scripts": {
+    "build": "bun run build.ts",
+    "dev": "bun run build.ts --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@floor/vlist": "link:../vlist",
+    "@types/bun": "^1.0.0",
+    "@types/react": "^19.2.13",
+    "bun": "^1.0.0",
+    "react": "^19.2.4",
+    "typescript": "^5.0.0"
+  }
+}