@floor/vlist 0.6.2 → 0.7.0

package/README.md

@@ -764,104 +764,99 @@ const list = vlist({
 
 ## Framework Adapters
 
+Framework-specific adapters are available as separate packages for easier integration and smaller bundle sizes.
+
 ### React
 
-```typescript
-import { vlist, withSelection } from 'vlist';
-import { useEffect, useRef } from 'react';
+**Package:** [`vlist-react`](https://github.com/floor/vlist-react) - 1.4 KB (0.6 KB gzipped)
 
-function MyList({ items }) {
-  const containerRef = useRef(null);
-  const listRef = useRef(null);
+```bash
+npm install @floor/vlist vlist-react
+```
 
-  useEffect(() => {
-    if (!containerRef.current) return;
+```tsx
+import { useVList } from 'vlist-react';
+import '@floor/vlist/styles';
 
-    listRef.current = vlist({
-      container: containerRef.current,
-      items,
-      item: { height: 48, template: renderItem },
-    })
-      .use(withSelection({ mode: 'single' }))
-      .build();
+function UserList({ users }) {
+  const { containerRef, instanceRef } = useVList({
+    item: {
+      height: 48,
+      template: (user) => `<div class="user">${user.name}</div>`,
+    },
+    items: users,
+  });
 
-    return () => listRef.current?.destroy();
-  }, []);
+  return <div ref={containerRef} style={{ height: 400 }} />;
+}
+```
 
-  useEffect(() => {
-    listRef.current?.setItems(items);
-  }, [items]);
+**Documentation:** [github.com/floor/vlist-react](https://github.com/floor/vlist-react)
 
-  return <div ref={containerRef} />;
-}
+### Vue
+
+**Package:** [`vlist-vue`](https://github.com/floor/vlist-vue) - 1.1 KB (0.6 KB gzipped)
+
+```bash
+npm install @floor/vlist vlist-vue
 ```
 
-### Vue 3
+```vue
+<script setup>
+import { useVList } from 'vlist-vue';
+import '@floor/vlist/styles';
 
-```typescript
-import { vlist, withSelection } from 'vlist';
-import { ref, onMounted, onUnmounted, watch } from 'vue';
-
-export default {
-  setup() {
-    const container = ref(null);
-    const list = ref(null);
-
-    onMounted(() => {
-      list.value = vlist({
-        container: container.value,
-        items: items.value,
-        item: { height: 48, template: renderItem },
-      })
-        .use(withSelection({ mode: 'single' }))
-        .build();
-    });
-
-    watch(items, (newItems) => {
-      list.value?.setItems(newItems);
-    });
-
-    onUnmounted(() => {
-      list.value?.destroy();
-    });
-
-    return { container };
+const users = ref([...]);
+
+const { containerRef, instance } = useVList({
+  item: {
+    height: 48,
+    template: (user) => `<div class="user">${user.name}</div>`,
   },
-};
+  items: users,
+});
+</script>
+
+<template>
+  <div ref="containerRef" style="height: 400px" />
+</template>
 ```
 
+**Documentation:** [github.com/floor/vlist-vue](https://github.com/floor/vlist-vue)
+
 ### Svelte
 
-```typescript
+**Package:** [`vlist-svelte`](https://github.com/floor/vlist-svelte) - 0.9 KB (0.5 KB gzipped)
+
+```bash
+npm install @floor/vlist vlist-svelte
+```
+
+```svelte
 <script>
-  import { vlist, withSelection } from 'vlist';
-  import { onMount, onDestroy } from 'svelte';
-
-  export let items = [];
-  
-  let container;
-  let list;
-
-  onMount(() => {
-    list = vlist({
-      container,
-      items,
-      item: { height: 48, template: renderItem },
-    })
-      .use(withSelection({ mode: 'single' }))
-      .build();
-  });
+  import { vlist } from 'vlist-svelte';
+  import '@floor/vlist/styles';
 
-  $: list?.setItems(items);
+  let users = [...];
+  let instance;
 
-  onDestroy(() => {
-    list?.destroy();
-  });
+  const config = {
+    item: {
+      height: 48,
+      template: (user) => `<div class="user">${user.name}</div>`,
+    },
+    items: users,
+  };
 </script>
 
-<div bind:this={container}></div>
+<div
+  use:vlist={{ config, onInstance: (i) => (instance = i) }}
+  style="height: 400px"
+/>
 ```
 
+**Documentation:** [github.com/floor/vlist-svelte](https://github.com/floor/vlist-svelte)
+
 ## Styling
 
 Import the base styles:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floor/vlist",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Lightweight, high-performance virtual list with zero dependencies",
   "author": {
     "name": "Floor IO",
@@ -34,39 +34,18 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
-    "./react": {
-      "types": "./dist/adapters/react.d.ts",
-      "import": "./dist/react/index.js",
-      "default": "./dist/react/index.js"
-    },
-    "./vue": {
-      "types": "./dist/adapters/vue.d.ts",
-      "import": "./dist/vue/index.js",
-      "default": "./dist/vue/index.js"
-    },
-    "./svelte": {
-      "types": "./dist/adapters/svelte.d.ts",
-      "import": "./dist/svelte/index.js",
-      "default": "./dist/svelte/index.js"
-    },
     "./styles": "./dist/vlist.css",
     "./styles/extras": "./dist/vlist-extras.css",
     "./package.json": "./package.json"
   },
-  "peerDependencies": {
-    "react": ">=17.0.0",
-    "vue": ">=3.0.0"
-  },
-  "peerDependenciesMeta": {
-    "react": {
-      "optional": true
-    },
-    "vue": {
-      "optional": true
-    }
-  },
   "files": [
-    "dist"
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.css",
+    "!dist/**/*.d.ts.map",
+    "!dist/core/lite.d.ts",
+    "!dist/core/minimal.d.ts",
+    "!dist/adapters/**"
   ],
   "sideEffects": [
     "*.css"

package/dist/adapters/index.d.ts

@@ -1,20 +0,0 @@
-/**
- * vlist adapters — Framework integration wrappers
- *
- * Each adapter is exported from its own subpath for tree-shaking:
- *   - `vlist/react`  — React hook
- *   - `vlist/vue`    — Vue 3 composable
- *   - `vlist/svelte` — Svelte action
- *
- * This barrel file is NOT intended for direct import.
- * Import from the framework-specific subpath instead.
- *
- * @packageDocumentation
- */
-export { useVList as useVListReact, useVListEvent } from "./react";
-export type { UseVListConfig as UseVListConfigReact, UseVListReturn as UseVListReturnReact, } from "./react";
-export { useVList as useVListVue, useVListEvent as useVListEventVue } from "./vue";
-export type { UseVListConfig as UseVListConfigVue, UseVListConfigInput as UseVListConfigInputVue, UseVListReturn as UseVListReturnVue, } from "./vue";
-export { vlist, onVListEvent } from "./svelte";
-export type { VListActionConfig, VListActionOptions, VListActionReturn, OnInstanceCallback, } from "./svelte";
-//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,QAAQ,IAAI,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnE,YAAY,EACV,cAAc,IAAI,mBAAmB,EACrC,cAAc,IAAI,mBAAmB,GACtC,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,QAAQ,IAAI,WAAW,EAAE,aAAa,IAAI,gBAAgB,EAAE,MAAM,OAAO,CAAC;AACnF,YAAY,EACV,cAAc,IAAI,iBAAiB,EACnC,mBAAmB,IAAI,sBAAsB,EAC7C,cAAc,IAAI,iBAAiB,GACpC,MAAM,OAAO,CAAC;AAGf,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC/C,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,UAAU,CAAC"}

package/dist/adapters/react.d.ts

@@ -1,119 +0,0 @@
-/**
- * vlist/react — Thin React wrapper for vlist
- *
- * Provides a `useVList` hook that manages the vlist lifecycle
- * within React's component model. The hook creates a vlist instance
- * on mount, syncs items reactively, and destroys on unmount.
- *
- * @packageDocumentation
- */
-import type { VListConfig, VListItem, VList, VListEvents, EventHandler } from "../types";
-/** 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> {
-    /**
-     * Ref to attach to your container element.
-     *
-     * ```tsx
-     * const { containerRef } = useVList(config);
-     * return <div ref={containerRef} style={{ height: 400 }} />;
-     * ```
-     */
-    containerRef: React.RefObject<HTMLDivElement | null>;
-    /**
-     * Ref holding the underlying vlist instance.
-     * Populated after mount, `null` before.
-     *
-     * Use `.current` to access vlist methods:
-     * ```tsx
-     * const handleJump = () => instanceRef.current?.scrollToIndex(100);
-     * ```
-     */
-    instanceRef: React.RefObject<VList<T> | null>;
-    /**
-     * Stable helper to get the vlist instance (or null).
-     * Convenient for inline usage without `.current`:
-     * ```tsx
-     * onClick={() => getInstance()?.scrollToIndex(0)}
-     * ```
-     */
-    getInstance: () => VList<T> | null;
-}
-/**
- * React hook for vlist integration.
- *
- * Creates a virtual list instance bound to a container ref.
- * The instance is created on mount and destroyed on unmount.
- * When `config.items` changes (by reference), items are synced automatically.
- *
- * **Usage:**
- * ```tsx
- * import { useVList } from 'vlist/react';
- *
- * function UserList({ users }) {
- *   const { containerRef, instanceRef } = useVList({
- *     item: {
- *       height: 48,
- *       template: (user) => `<div class="user">${user.name}</div>`,
- *     },
- *     items: users,
- *     selection: { mode: 'single' },
- *   });
- *
- *   return (
- *     <div
- *       ref={containerRef}
- *       style={{ height: 400 }}
- *       onClick={() => {
- *         const selected = instanceRef.current?.getSelected();
- *         console.log('Selected:', selected);
- *       }}
- *     />
- *   );
- * }
- * ```
- *
- * **With adapter (async/infinite scroll):**
- * ```tsx
- * const { containerRef } = useVList({
- *   item: {
- *     height: 64,
- *     template: (item) => `<div>${item.title}</div>`,
- *   },
- *   adapter: {
- *     read: async ({ offset, limit }) => {
- *       const res = await fetch(`/api/items?offset=${offset}&limit=${limit}`);
- *       const data = await res.json();
- *       return { items: data.items, total: data.total };
- *     },
- *   },
- * });
- * ```
- *
- * @param config - VList configuration (without `container`)
- * @returns containerRef, instanceRef, and getInstance helper
- */
-export declare function useVList<T extends VListItem = VListItem>(config: UseVListConfig<T>): UseVListReturn<T>;
-/**
- * Subscribe to a vlist event within React's lifecycle.
- * Automatically unsubscribes on unmount or when the handler changes.
- *
- * ```tsx
- * const { instanceRef } = useVList(config);
- *
- * useVListEvent(instanceRef, 'selection:change', ({ selected }) => {
- *   console.log('Selected items:', selected);
- * });
- *
- * useVListEvent(instanceRef, 'scroll', ({ scrollTop, direction }) => {
- *   console.log(`Scrolling ${direction} at ${scrollTop}px`);
- * });
- * ```
- *
- * @param instanceRef - Ref to the vlist instance (from useVList)
- * @param event - Event name
- * @param handler - Event handler
- */
-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;
-//# sourceMappingURL=react.d.ts.map

package/dist/adapters/react.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../../src/adapters/react.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACT,KAAK,EACL,WAAW,EACX,YAAY,EAEb,MAAM,UAAU,CAAC;AAMlB,iEAAiE;AACjE,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,IAAI,IAAI,CAChE,WAAW,CAAC,CAAC,CAAC,EACd,WAAW,CACZ,CAAC;AAEF,0CAA0C;AAC1C,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IAC7D;;;;;;;OAOG;IACH,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAErD;;;;;;;;OAQG;IACH,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAE9C;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CACpC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EACtD,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GACxB,cAAc,CAAC,CAAC,CAAC,CAqDnB;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,CAAC,SAAS,SAAS,EACnB,CAAC,SAAS,MAAM,WAAW,CAAC,CAAC,CAAC,EAE9B,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAC7C,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACvC,IAAI,CAmBN"}

package/dist/adapters/svelte.d.ts

@@ -1,198 +0,0 @@
-/**
- * vlist/svelte — Thin Svelte wrapper for vlist
- *
- * Provides a `vlist` action that manages the vlist lifecycle
- * within Svelte's component model. The action creates a vlist instance
- * when the element mounts, syncs items on update, and destroys on unmount.
- *
- * Works with both Svelte 4 and Svelte 5 (actions are framework-stable).
- * No Svelte imports needed — actions are plain functions.
- *
- * @packageDocumentation
- */
-import type { VListConfig, VListItem, VList, VListEvents, EventHandler, Unsubscribe } from "../types";
-/** Configuration for the vlist action (VListConfig without container) */
-export type VListActionConfig<T extends VListItem = VListItem> = Omit<VListConfig<T>, "container">;
-/**
- * Callback invoked once the vlist instance is ready.
- * Use this to subscribe to events, call methods, or store a reference.
- */
-export type OnInstanceCallback<T extends VListItem = VListItem> = (instance: VList<T>) => void;
-/** Full options passed to the vlist action */
-export interface VListActionOptions<T extends VListItem = VListItem> {
-    /** VList configuration (without container) */
-    config: VListActionConfig<T>;
-    /**
-     * Called once the instance is created (on mount).
-     * Use this to get a reference to the vlist instance for calling methods.
-     *
-     * ```svelte
-     * <script>
-     *   let vlistInstance;
-     *   const options = {
-     *     config: { ... },
-     *     onInstance: (inst) => { vlistInstance = inst; },
-     *   };
-     * </script>
-     * <div use:vlist={options} />
-     * <button on:click={() => vlistInstance?.scrollToIndex(0)}>Top</button>
-     * ```
-     */
-    onInstance?: OnInstanceCallback<T>;
-}
-/** Svelte action return type */
-export interface VListActionReturn<T extends VListItem = VListItem> {
-    /** Called by Svelte when the action parameter changes */
-    update?: (newOptions: VListActionOptions<T>) => void;
-    /** Called by Svelte when the element is removed from the DOM */
-    destroy?: () => void;
-}
-/**
- * Svelte action for vlist integration.
- *
- * Attaches a virtual list to the target element. The list is created
- * when the element mounts and destroyed when it unmounts. Passing
- * new options via Svelte's reactivity triggers an update.
- *
- * **Basic usage:**
- * ```svelte
- * <script>
- *   import { vlist } from 'vlist/svelte';
- *
- *   const users = [
- *     { id: 1, name: 'Alice' },
- *     { id: 2, name: 'Bob' },
- *   ];
- *
- *   const options = {
- *     config: {
- *       item: {
- *         height: 48,
- *         template: (user) => `<div class="user">${user.name}</div>`,
- *       },
- *       items: users,
- *     },
- *   };
- * </script>
- *
- * <div use:vlist={options} style="height: 400px" />
- * ```
- *
- * **With instance access (for methods):**
- * ```svelte
- * <script>
- *   import { vlist } from 'vlist/svelte';
- *
- *   let instance;
- *
- *   const options = {
- *     config: {
- *       item: {
- *         height: 48,
- *         template: (item) => `<div>${item.name}</div>`,
- *       },
- *       items: users,
- *       selection: { mode: 'single' },
- *     },
- *     onInstance: (inst) => { instance = inst; },
- *   };
- *
- *   function jumpToTop() {
- *     instance?.scrollToIndex(0);
- *   }
- * </script>
- *
- * <div use:vlist={options} style="height: 400px" />
- * <button on:click={jumpToTop}>Jump to top</button>
- * ```
- *
- * **Reactive items (Svelte 4):**
- * ```svelte
- * <script>
- *   import { vlist } from 'vlist/svelte';
- *
- *   let users = [...];
- *
- *   // Svelte re-runs the action's update when this object changes
- *   $: options = {
- *     config: {
- *       item: { height: 48, template: (u) => `<div>${u.name}</div>` },
- *       items: users,
- *     },
- *   };
- * </script>
- *
- * <div use:vlist={options} style="height: 400px" />
- * ```
- *
- * **With adapter (async/infinite scroll):**
- * ```svelte
- * <script>
- *   import { vlist } from 'vlist/svelte';
- *
- *   const options = {
- *     config: {
- *       item: {
- *         height: 64,
- *         template: (item) => `<div>${item.title}</div>`,
- *       },
- *       adapter: {
- *         read: async ({ offset, limit }) => {
- *           const res = await fetch(`/api/items?offset=${offset}&limit=${limit}`);
- *           const data = await res.json();
- *           return { items: data.items, total: data.total };
- *         },
- *       },
- *     },
- *   };
- * </script>
- *
- * <div use:vlist={options} style="height: 400px" />
- * ```
- *
- * @param node - The DOM element Svelte binds the action to
- * @param options - Configuration and callbacks
- * @returns Action lifecycle object (update + destroy)
- */
-export declare function vlist<T extends VListItem = VListItem>(node: HTMLElement, options: VListActionOptions<T>): VListActionReturn<T>;
-/**
- * Helper to subscribe to vlist events with automatic cleanup.
- * Returns an unsubscribe function.
- *
- * ```svelte
- * <script>
- *   import { vlist, onVListEvent } from 'vlist/svelte';
- *   import { onDestroy } from 'svelte';
- *
- *   let instance;
- *   let unsubs = [];
- *
- *   function handleInstance(inst) {
- *     instance = inst;
- *
- *     unsubs.push(
- *       onVListEvent(inst, 'selection:change', ({ selected }) => {
- *         console.log('Selected:', selected);
- *       })
- *     );
- *
- *     unsubs.push(
- *       onVListEvent(inst, 'scroll', ({ scrollTop, direction }) => {
- *         console.log(`Scrolling ${direction} at ${scrollTop}px`);
- *       })
- *     );
- *   }
- *
- *   onDestroy(() => unsubs.forEach(fn => fn()));
- * </script>
- *
- * <div use:vlist={{ config, onInstance: handleInstance }} />
- * ```
- *
- * @param instance - The vlist instance
- * @param event - Event name
- * @param handler - Event handler
- * @returns Unsubscribe function
- */
-export declare function onVListEvent<T extends VListItem, K extends keyof VListEvents<T>>(instance: VList<T>, event: K, handler: EventHandler<VListEvents<T>[K]>): Unsubscribe;
-//# sourceMappingURL=svelte.d.ts.map

package/dist/adapters/svelte.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"svelte.d.ts","sourceRoot":"","sources":["../../src/adapters/svelte.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACT,KAAK,EACL,WAAW,EACX,YAAY,EACZ,WAAW,EACZ,MAAM,UAAU,CAAC;AAMlB,yEAAyE;AACzE,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,IAAI,IAAI,CACnE,WAAW,CAAC,CAAC,CAAC,EACd,WAAW,CACZ,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,IAAI,CAChE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,KACf,IAAI,CAAC;AAEV,8CAA8C;AAC9C,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IACjE,8CAA8C;IAC9C,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAE7B;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;CACpC;AAED,gCAAgC;AAChC,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IAChE,yDAAyD;IACzD,MAAM,CAAC,EAAE,CAAC,UAAU,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAErD,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0GG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EACnD,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC7B,iBAAiB,CAAC,CAAC,CAAC,CA4BtB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,YAAY,CAC1B,CAAC,SAAS,SAAS,EACnB,CAAC,SAAS,MAAM,WAAW,CAAC,CAAC,CAAC,EAE9B,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,EAClB,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACvC,WAAW,CAEb"}