### VirtualList with Dynamic Sizing and Scroll Control Example

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/types.md

Example demonstrating a VirtualList with dynamic item sizing and scroll-to-index functionality.

```svelte
<!-- With dynamic sizing and control -->
<VirtualList
  height={600}
  itemCount={data.length}
  itemSize={(i) => data[i].height}
  scrollToIndex={250}
  scrollToAlignment="center"
/>
```

--------------------------------

### Basic Virtual List Example

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/QUICK_START.md

A fundamental example demonstrating a vertical virtual list with 10000 items and fixed item sizes.

```svelte
<script>
  import VirtualList from 'svelte-tiny-virtual-list';

  const data = Array.from({ length: 10000 }, (_, i) => `Item ${i}`);
</script>

<VirtualList width="100%" height={600} itemCount={data.length} itemSize={50}>
  {#snippet item({ style, index })}
    <div {style}>
      {data[index]}
    </div>
  {/snippet}
</VirtualList>
```

--------------------------------

### Horizontal VirtualList Example

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/types.md

Example of rendering a horizontal VirtualList with precise dimensions. Width is required.

```svelte
<!-- Horizontal with precise dimensions -->
<VirtualList
  scrollDirection="horizontal"
  width={1200}
  height={200}
  itemCount={data.length}
  itemSize={150}
/>
```

--------------------------------

### TypeScript Setup for VirtualList

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/EXPORTS.md

Demonstrates the complete TypeScript setup for using the VirtualList component, including defining props, event handlers, item size getters, and alignment.

```typescript
import VirtualList from 'svelte-tiny-virtual-list';
import type {
  VirtualListProps,
  VirtualListEvents,
  Alignment,
  ItemSize
} from 'svelte-tiny-virtual-list';

// Type your props
const props: VirtualListProps = {
  itemCount: 100,
  itemSize: 50,
  height: 600
};

// Type your event handlers
const handlers: VirtualListEvents = {
  onItemsUpdated: ({ start, end }) => {
    console.log(`Items ${start}-${end} visible`);
  }
};

// Type item size function
const sizeGetter: ItemSize = (index) => {
  return 50 + (index % 2) * 10;
};

// Type alignment parameter
const alignment: Alignment = 'center';
```

--------------------------------

### Example ItemSizeGetter Implementations

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/types.md

Provides examples of how to implement the ItemSizeGetter type for alternating item sizes or sizes derived from data.

```typescript
const getItemSize: ItemSizeGetter = (index) => {
  return 50 + (index % 2) * 10; // Alternate between 50px and 60px
};

const getItemSizeFromData: ItemSizeGetter = (index) => {
  return items[index].displayHeight;
};
```

--------------------------------

### Vertical VirtualList Example

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/types.md

Example of rendering a vertical VirtualList with fixed dimensions. Height is required.

```svelte
<script>
  const data = Array.from({ length: 10000 }, (_, i) => i);
</script>

<!-- Vertical with fixed dimensions -->
<VirtualList
  height={600}
  width="100%"
  itemCount={data.length}
  itemSize={50}
/>
```

--------------------------------

### Install svelte-tiny-virtual-list with pnpm

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/README.md

Use pnpm to add the svelte-tiny-virtual-list package to your project dependencies.

```shell
pnpm install svelte-tiny-virtual-list
```

--------------------------------

### Svelte Example using Alignment

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/types.md

Demonstrates how to use the scrollToAlignment prop in a VirtualList component to center a specific item.

```svelte
<VirtualList
  scrollToIndex={500}
  scrollToAlignment="center"
/>
```

--------------------------------

### Install svelte-tiny-virtual-list with npm

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/README.md

Use npm to add the svelte-tiny-virtual-list package to your project dependencies.

```shell
npm install svelte-tiny-virtual-list
```

--------------------------------

### Virtual List Item Size Examples

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/types.md

Illustrates different ways to configure the `itemSize` prop for the VirtualList component, including fixed, array-based, and dynamic sizing.

```svelte
<!-- Fixed size -->
<VirtualList itemSize={50} />
```

```svelte
<!-- Array of sizes -->
<VirtualList itemSize={[40, 80]} />
```

```svelte
<!-- Function for dynamic sizing -->
<VirtualList itemSize={(index) => data[index].height} />
```

--------------------------------

### Basic Virtual List Usage

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/INDEX.md

This example shows how to set up a virtual list with a large dataset, a button to jump to a specific item, and custom header and item rendering. It also includes basic styling and event logging for visible items.

```svelte
<script>
  import VirtualList from 'svelte-tiny-virtual-list';

  const data = Array.from({ length: 100000 }, (_, i) => `Item ${i}`);
  let scrollToIndex = -1;

  function jumpToItem(index) {
    scrollToIndex = index;
  }
</script>

<button onclick={() => jumpToItem(5000)}>Jump to Item 5000</button>

<VirtualList
  width="100%"
  height={600}
  itemCount={data.length}
  itemSize={50}
  scrollToAlignment="center"
  scrollToBehaviour="smooth"
  {scrollToIndex}
  onItemsUpdated={({ start, end }) => console.log(`Visible: ${start}-${end}`)}
>
  {#snippet item({ style, index })}
    <div {style} class="item">{data[index]}</div>
  {/snippet}

  {#snippet header()}
    <div class="header">My Virtual List</div>
  {/snippet}
</VirtualList>

<style>
  :global(.virtual-list-wrapper) {
    border: 1px solid #ddd;
  }

  :global(.item) {
    padding: 10px;
    border-bottom: 1px solid #eee;
  }
</style>
```

--------------------------------

### Svelte Example using ScrollBehaviour

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/types.md

Shows how to implement smooth scrolling to a specific index in a VirtualList component using the scrollToBehaviour prop.

```svelte
<VirtualList
  scrollToIndex={100}
  scrollToBehaviour="smooth"
/>
```

--------------------------------

### Integrated Constant Usage Example

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/constants.md

Shows how to use various constants together for handling user scrolling, calculating target offsets, and applying programmatic scrolls with smooth behavior.

```javascript
import { DIRECTION, ALIGNMENT, SCROLL_PROP, SCROLL_PROP_LEGACY } from './constants.js';

// User scrolls vertically
const scrollDirection = DIRECTION.VERTICAL;
const currentOffset = element[SCROLL_PROP_LEGACY[scrollDirection]]; // element.scrollTop

// Scroll to item 500, centered
const targetOffset = getUpdatedOffsetForIndex(
  ALIGNMENT.CENTER,
  containerHeight,
  currentOffset,
  500
);

// Apply programmatic scroll
element.scroll({
  [SCROLL_PROP[scrollDirection]]: targetOffset,
  behavior: 'smooth'
});
// Result: element.scroll({ top: targetOffset, behavior: 'smooth' })
```

--------------------------------

### Install svelte-tiny-virtual-list with yarn

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/README.md

Use yarn to add the svelte-tiny-virtual-list package to your project dependencies.

```shell
yarn add svelte-tiny-virtual-list
```

--------------------------------

### Basic Vertical List Example

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/VirtualList.md

Demonstrates the basic usage of VirtualList for rendering a simple vertical list with fixed item heights. Ensure the component is imported and data is provided.

```svelte
<script>
  import VirtualList from 'svelte-tiny-virtual-list';

  const data = Array.from({ length: 10000 }, (_, i) => `Item ${i}`);
</script>

<VirtualList width="100%" height={600} itemCount={data.length} itemSize={50}>
  {#snippet item({ style, index })}
    <div {style} class="item">{data[index]}</div>
  {/snippet}
</VirtualList>

<style>
  :global(.item) {
    display: flex;
    align-items: center;
    padding: 0 10px;
    border-bottom: 1px solid #eee;
  }
</style>
```

--------------------------------

### Using VirtualList Event Handlers

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/types.md

Example of how to implement and pass event handlers to the VirtualList component. Ensure the handler functions match the expected signature.

```svelte
<script>
  function handleItemsUpdated({ start, end }) {
    console.log(`Visible items: ${start} to ${end}`);
  }

  function handleAfterScroll({ offset, event }) {
    console.log(`Scrolled to ${offset}px`);
  }
</script>

<VirtualList
  {onItemsUpdated}
  {onAfterScroll}
  itemCount={1000}
  itemSize={50}
  height={600}
/>
```

--------------------------------

### Scroll to Index Example

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/VirtualList.md

Demonstrates how to programmatically scroll the list to a specific item. Use the `scrollToIndex`, `scrollToAlignment`, and `scrollToBehaviour` props to control the scrolling behavior.

```svelte
<script>
  import VirtualList from 'svelte-tiny-virtual-list';

  const data = Array.from({ length: 10000 }, (_, i) => `Item ${i}`);
  let scrollToIndex = -1;

  function scrollToItem(index) {
    scrollToIndex = index;
  }
</script>

<button onclick={() => scrollToItem(500)}>Jump to item 500</button>
<button onclick={() => scrollToItem(0)}>Back to top</button>

<VirtualList
  width="100%"
  height={600}
  {itemCount: data.length}
  itemSize={50}
  {scrollToIndex}
  scrollToAlignment="center"
  scrollToBehaviour="smooth"
>
  {#snippet item({ style, index })}
    <div {style}>{data[index]}</div>
  {/snippet}
</VirtualList>
```

--------------------------------

### Horizontal Virtual List

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/QUICK_START.md

Example of a horizontal virtual list with 500 items, each with a width of 250 pixels.

```svelte
<VirtualList
  scrollDirection="horizontal"
  width={1200}
  height={200}
  itemCount={500}
  itemSize={250}
>
  {#snippet item({ style, index })}
    <div {style} class="card">Card {index}</div>
  {/snippet}
</VirtualList>
```

--------------------------------

### Example Usage of onAfterScroll

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/types.md

Demonstrates how to use the `onAfterScroll` event handler to detect when a user has scrolled past a certain offset. This snippet is for Svelte.

```svelte
<script>
  function onAfterScroll({ event, offset }) {
    if (offset > 1000) {
      console.log('User scrolled past 1000px');
    }
  }
</script>

<VirtualList
  {onAfterScroll}
  itemCount={10000}
  itemSize={50}
  height={600}
/>
```

--------------------------------

### Virtual List with Animations

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/advanced-usage.md

Apply Svelte transitions to items within VirtualList for animated loading. The example uses a staggered loading approach with `fade` transition.

```svelte
<script>
  import { fade } from 'svelte/transition';
  import VirtualList from 'svelte-tiny-virtual-list';

  let items = $state([]);

  async function loadItems() {
    // Stagger load items
    for (let i = 0; i < 100; i++) {
      await new Promise(r => setTimeout(r, 10));
      items = [...items, `Item ${i}`];
    }
  }
</script>

<VirtualList
  itemCount={items.length}
  itemSize={50}
  height={600}
  width="100%"
>
  {#snippet item({ style, index })}
    <div {style} in:fade={{ duration: 300 }}>
      {items[index]}
    </div>
  {/snippet}
</VirtualList>
```

--------------------------------

### Item Size - Fixed Number Example

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/types.md

Use a fixed number to set a uniform size for all items in the virtual list. This is the most performant option.

```typescript
itemSize={50} // All items are 50px tall
```

--------------------------------

### Virtual List Direction Examples

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/types.md

Demonstrates how to configure the scroll direction for the VirtualList component. The default is vertical scrolling.

```svelte
<!-- Vertical list (default) -->
<VirtualList height={600} width="100%" />
```

```svelte
<!-- Horizontal list -->
<VirtualList scrollDirection="horizontal" width={800} height={200} />
```

--------------------------------

### Vertical List with Fixed Height Items

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/QUICK_START.md

Example of a vertical virtual list with 1000 items, each having a fixed height of 50 pixels.

```svelte
<VirtualList
  width="100%"
  height={600}
  itemCount={1000}
  itemSize={50}
>
  {#snippet item({ style, index })}
    <div {style}>Item {index}</div>
  {/snippet}
</VirtualList>
```

--------------------------------

### Render VirtualList with Snippets

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/types.md

Example of using the VirtualList component with item, header, and footer snippets. Ensure the 'style' prop is applied to the item element.

```svelte
<VirtualList itemCount={100} itemSize={50} height={600} width="100%">
  {#snippet item({ index, style })} 
    <div {style} class="list-item">
      Item {index}
    </div>
  {/snippet}

  {#snippet header()} 
    <div class="list-header">My List</div>
  {/snippet}

  {#snippet footer()} 
    <div class="list-footer">End of list</div>
  {/snippet}
</VirtualList>

```

--------------------------------

### SCROLL_PROP Internal Usage Examples

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/constants.md

Shows how to apply programmatic scroll using SCROLL_PROP to dynamically set the scroll property based on direction. Examples for vertical and horizontal scrolling are provided.

```javascript
// Apply programmatic scroll
wrapper.scroll({
  [SCROLL_PROP[scrollDirection]]: scroll.offset,
  behavior: scrollToBehaviour
});
```

```javascript
// For vertical: wrapper.scroll({ top: 1200, behavior: 'instant' })
// For horizontal: wrapper.scroll({ left: 800, behavior: 'instant' })
```

--------------------------------

### Configure Initial Scroll Offset

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/configuration.md

Sets the initial scroll position of the list in pixels. This allows the list to start at a specific offset.

```svelte
<VirtualList
  scrollOffset={1200} // Start scrolled down 1200px
/>
```

--------------------------------

### Infinite Loading Example

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/VirtualList.md

Integrates VirtualList with an infinite loading mechanism using `svelte-infinite-loading`. The `footer` slot can be used to place the `InfiniteLoading` component, which triggers data fetching when the user scrolls near the end.

```svelte
<script>
  import VirtualList from 'svelte-tiny-virtual-list';
  import InfiniteLoading from 'svelte-infinite-loading';

  let data = $state(['A', 'B', 'C', 'D', 'E', 'F']);

  function infiniteHandler({ detail: { complete, error } }) {
    try {
      // Simulate API call
      const newData = ['G', 'H', 'I', 'J', 'K', 'L'];
      data = [...data, ...newData];
      complete();
    } catch (e) {
      error();
    }
  }
</script>

<VirtualList width="100%" height={600} itemCount={data.length} itemSize={50}>
  {#snippet item({ style, index })}
    <div {style}>{data[index]}</div>
  {/snippet}

  {#snippet footer()}
    <InfiniteLoading on:infinite={infiniteHandler} />
  {/snippet}
</VirtualList>
```

--------------------------------

### Interactive Items with Selection

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/advanced-usage.md

Implement interactive list items that support selection and keyboard navigation. This example uses `onclick` and `onkeydown` handlers to manage the selected state and arrow key navigation.

```svelte
<script>
  import VirtualList from 'svelte-tiny-virtual-list';

  const items = $state(Array.from({ length: 100 }, (_, i) => i));
  let selectedIndex = $state(-1);

  function selectItem(index) {
    selectedIndex = index;
  }

  function handleKeydown(e, index) {
    if (e.key === 'ArrowUp' && index > 0) {
      selectItem(index - 1);
    } else if (e.key === 'ArrowDown' && index < items.length - 1) {
      selectItem(index + 1);
    }
  }
</script>

<VirtualList
  itemCount={items.length}
  itemSize={50}
  height={600}
  width="100%"
>
  {#snippet item({ style, index })}
    <div
      {style}
      class="item"
      class:selected={index === selectedIndex}
      onclick={() => selectItem(index)}
      onkeydown={(e) => handleKeydown(e, index)}
      tabindex="0"
    >
      Item {items[index]}
    </div>
  {/snippet}
</VirtualList>

<style>
  :global(.item) {
    padding: 10px;
    cursor: pointer;
    border-bottom: 1px solid #eee;
  }

  :global(.item.selected) {
    background: #e3f2fd;
    color: #1976d2;
  }
</style>
```

--------------------------------

### Item Size - Array of Numbers Example

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/types.md

Provide an array of numbers to specify individual sizes for each item. The array length must be at least the item count.

```typescript
itemSize={[50, 60, 45, 70, 55]} // Item sizes specified individually
```

--------------------------------

### SCROLL_CHANGE_REASON Internal Usage Examples

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/constants.md

Demonstrates how to set and check the SCROLL_CHANGE_REASON when updating scroll state. Different handling is applied based on the change reason.

```javascript
// When user scrolls
scroll = { offset, changeReason: SCROLL_CHANGE_REASON.OBSERVED };
```

```javascript
// When prop-driven scroll
scroll = {
  offset: getOffsetForIndex(scrollToIndex),
  changeReason: SCROLL_CHANGE_REASON.REQUESTED
};
```

```javascript
// Different handling based on reason
if (scroll.changeReason === SCROLL_CHANGE_REASON.REQUESTED) {
  wrapper.scroll({
    [SCROLL_PROP[scrollDirection]]: scroll.offset,
    behavior: scrollToBehaviour
  });
}
```

--------------------------------

### Make Multiple Items Sticky

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/configuration.md

Provide an array of item indexes to the `stickyIndices` prop to make multiple items sticky. This example shows the first three items being made sticky.

```svelte
<!-- Multiple sticky items -->
<VirtualList
  stickyIndices={[0, 1, 2]} 
  itemCount={data.length}
  itemSize={50}
/>
```

--------------------------------

### Item Size - Dynamic Getter Function Example

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/types.md

Implement an ItemSizeGetter function to dynamically calculate each item's size based on its index. This is suitable for very large, dynamic lists.

```typescript
itemSize={(index) => {
  return data[index].height; // Get size from data
}}
```

--------------------------------

### Basic VirtualList Usage

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/VirtualList.md

Demonstrates the fundamental structure for using the VirtualList component. Ensure you provide required props like itemCount, itemSize, and height/width.

```svelte
<script>
  import VirtualList from 'svelte-tiny-virtual-list';

  let items = Array.from({ length: 1000 }, (_, i) => `Item ${i + 1}`);
  let itemCount = items.length;
  let itemSize = 50; // Height of each item in pixels
</script>

<VirtualList
  width={300} // Width of the viewport
  height={400} // Height of the viewport
  itemCount={itemCount}
  itemSize={itemSize}
>
  {#snippet item({ index, style })}
    <div style={style} class="item">
      {items[index]}
    </div>
  {/snippet}
</VirtualList>

<style>
  .item {
    padding: 10px;
    border-bottom: 1px solid #eee;
  }
</style>
```

--------------------------------

### Optimize Item Size Calculation

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/advanced-usage.md

Demonstrates fast and slow methods for calculating item sizes. Prefer memoized lookups or O(1) calculations for the `itemSize` function to maintain performance.

```svelte
<script>
  // ✅ Fast: memoized, O(1) lookup
  const sizeMap = new Map();
  items.forEach((item, i) => sizeMap.set(i, item.height));

  function getSize(index) {
    return sizeMap.get(index) ?? 50;
  }

  // ❌ Slow: complex calculation each time
  function getSize_bad(index) {
    let size = 50;
    for (let i = 0; i < 100; i++) {
      size += Math.sin(i);
    }
    return size;
  }

  // ❌ Slow: array lookup with filtering
  function getSize_bad2(index) {
    const item = items.find(i => i.id === ids[index]);
    return item?.height ?? 50;
  }
</script>
```

--------------------------------

### Component Initialization Data Flow

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/architecture.md

Illustrates the sequence of events when the VirtualList component is first initialized.

```mermaid
graph TD
User_provides_props[User provides props (itemCount, itemSize, height, width, etc.)]
VirtualList_receives_props[VirtualList receives props via $props()]
Create_SizeAndPositionManager[Create SizeAndPositionManager with itemSize/itemCount/estimatedItemSize]
Initialize_scroll_state[Initialize scroll state: { offset: 0, changeReason: REQUESTED }]
Set_up_DOM_effect[Set up DOM effect to attach scroll event listener]
Render_visible_items[Render visible items calculated from offset]

User_provides_props --> VirtualList_receives_props --> Create_SizeAndPositionManager --> Initialize_scroll_state --> Set_up_DOM_effect --> Render_visible_items
```

--------------------------------

### VirtualList with Dynamic Item Sizes

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/VirtualList.md

Illustrates how to use a function for `itemSize` to handle lists where items have variable heights. This is crucial for dynamic content.

```svelte
<script>
  import VirtualList from 'svelte-tiny-virtual-list';

  let items = Array.from({ length: 1000 }, (_, i) => `Item ${i + 1} with potentially different content length.`);
  let itemCount = items.length;

  // Function to determine item size dynamically
  function calculateItemSize(index) {
    // Example: Larger items for even indices, smaller for odd
    return index % 2 === 0 ? 70 : 40;
  }
</script>

<VirtualList
  width={300}
  height={400}
  itemCount={itemCount}
  itemSize={calculateItemSize}
  estimatedItemSize={50} // Provide an estimate for better performance
>
  {#snippet item({ index, style })}
    <div style={style} class="item dynamic-item">
      {items[index]}
    </div>
  {/snippet}
</VirtualList>

<style>
  .dynamic-item {
    padding: 10px;
    border-bottom: 1px solid #eee;
    display: flex;
    align-items: center;
  }
</style>
```

--------------------------------

### Minimal Virtual List Configuration

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/configuration.md

Use this basic configuration for a simple list with a fixed number of items and a fixed item size.

```svelte
<VirtualList
  itemCount={100}
  itemSize={50}
  height={600}
/>
```

--------------------------------

### Load Data from Database/API

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/advanced-usage.md

Manage data loading from a remote source, handling initial loads and subsequent data fetching as the user scrolls. Use `getKey` for stable item identification.

```svelte
<script>
  import VirtualList from 'svelte-tiny-virtual-list';

  let items = $state([]);
  let totalCount = $state(0);
  let loading = $state(false);
  let virtualList;

  function getItemKey(index) {
    // Use database ID to handle reordering/updates
    return items[index]?.id || index;
  }

  async function loadInitial() {
    loading = true;
    const response = await fetch('/api/items?limit=100');
    const data = await response.json();
    items = data.items;
    totalCount = data.total;
    loading = false;
  }

  async function loadMore(startIndex) {
    const response = await fetch(`/api/items?offset=${startIndex}&limit=100`);
    const data = await response.json();
    items = [...items, ...data.items];
  }

  function onItemsUpdated({ start, end }) {
    // Preload next batch when approaching end
    if (end > items.length - 50) {
      loadMore(items.length);
    }
  }

  onMount(loadInitial);
</script>

{#if loading}
  <div class="loading">Loading...</div>
{:else}
  <VirtualList
    bind:this={virtualList}
    itemCount={items.length}
    itemSize={50}
    height={600}
    width="100%"
    getKey={getItemKey}
    onItemsUpdated
  >
    {#snippet item({ style, index })}
      <div {style} class="item">{items[index]?.name}</div>
    {/snippet}
  </VirtualList>
{/if}
```

--------------------------------

### onListItemsUpdate Prop

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/README.md

A function that fires when the set of visible items in the list is updated. It provides the start and end indices of the visible items.

```APIDOC
## onListItemsUpdate

### Description
Function that fires when the visible items are updated.

### Parameters
- **start** (number) - Index of the first visible item.
- **end** (number) - Index of the last visible item.
```

--------------------------------

### ItemsUpdatedDetail Interface Definition

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/EXPORTS.md

Represents the detail object passed to the `onItemsUpdated` event handler, indicating the start and end indices of the updated items.

```typescript
interface ItemsUpdatedDetail {
  start: number;
  end: number;
}
```

--------------------------------

### Alignment Type Definition

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/EXPORTS.md

Defines the possible values for controlling scroll alignment when scrolling to an item. Use 'auto', 'start', 'center', or 'end'.

```typescript
type Alignment = 'auto' | 'start' | 'center' | 'end'
```

--------------------------------

### Get Total List Size

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/SizeAndPositionManager.md

Retrieves the total calculated size of all items in the list. This is useful for setting the overall scrollable height/width of the container.

```javascript
const manager = new SizeAndPositionManager(50, 1000, 50);
const totalHeight = manager.getTotalSize();
console.log(`List height: ${totalHeight}px`);
```

--------------------------------

### Get Size and Position for an Item

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/SizeAndPositionManager.md

Retrieves the calculated size and offset for a specific item index. Useful for debugging or understanding item layout.

```javascript
const manager = new SizeAndPositionManager(50, 100, 50);
const { size, offset } = manager.getSizeAndPositionForIndex(10);
console.log(`Item 10: size=${size}px, offset=${offset}px`);
```

--------------------------------

### VirtualList with Custom Key

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/VirtualList.md

Demonstrates using the `getKey` prop to provide a custom unique identifier for each item. This is beneficial when dealing with data that has stable IDs, especially from external sources.

```svelte
<script>
  import VirtualList from 'svelte-tiny-virtual-list';

  // Example data with unique IDs
  let items = [
    { id: 'a1', name: 'Apple' },
    { id: 'b2', name: 'Banana' },
    { id: 'c3', name: 'Cherry' },
    // ... potentially thousands more
  ];
  let itemCount = items.length;
  let itemSize = 40;

  // Function to get the unique key for each item
  function getItemKey(index) {
    return items[index].id;
  }
</script>

<VirtualList
  width={300}
  height={400}
  itemCount={itemCount}
  itemSize={itemSize}
  getKey={getItemKey}
>
  {#snippet item({ index, style })}
    <div style={style} class="item">
      {items[index].name} (ID: {items[index].id})
    </div>
  {/snippet}
</VirtualList>

<style>
  .item {
    padding: 10px;
    border-bottom: 1px solid #eee;
  }
</style>
```

--------------------------------

### Basic Usage of VirtualList in Svelte

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/README.md

Demonstrates the basic implementation of the VirtualList component in Svelte, rendering a list of items with fixed sizes. Ensure the 'item' slot is used to define the rendering of each item.

```svelte
<script>
	import VirtualList from 'svelte-tiny-virtual-list';

	const data = ['A', 'B', 'C', 'D', 'E', 'F' /* ... */];
</script>

<VirtualList width="100%" height={600} itemCount={data.length} itemSize={50}>
	{#snippet item({ style, index })}
		<div {style}>
			Letter: {data[index]}, Row: #{index}
		</div>
	{/snippet}
</VirtualList>
```

--------------------------------

### Using ItemsUpdatedDetail in Svelte

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/types.md

Example demonstrating how to use the `ItemsUpdatedDetail` object within an `onItemsUpdated` handler in a Svelte component. This allows you to calculate the number of visible items.

```svelte
<script>
  function onItemsUpdated({ start, end }) {
    const visibleCount = end - start + 1;
    console.log(`${visibleCount} items visible`);
  }
</script>

<VirtualList
  onItemsUpdated
  itemCount={10000}
  itemSize={50}
  height={600}
/>
```

--------------------------------

### Realistic Production Virtual List with Dynamic Data

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/configuration.md

Configure a virtual list for production use with dynamic item loading, variable item heights, and event handling. Ensure to implement the fetch API for data loading and handle scroll events for potential further data loading.

```svelte
<script>
  import VirtualList from 'svelte-tiny-virtual-list';
  
  let items = $state([]);
  let selectedIndex = $state(-1);
  
  async function loadItems() {
    const response = await fetch('/api/items');
    items = await response.json();
  }
  
  function getItemKey(index) {
    return items[index].id;
  }
  
  function getItemHeight(index) {
    // Variable height based on content
    const content = items[index].description;
    return 40 + Math.ceil(content.length / 50) * 20;
  }
  
  function handleItemsUpdated({ start, end }) {
    console.log(`Visible: items ${start}-${end}`);
  }
  
  function handleScroll({ offset }) {
    if (offset > items.length * 50 * 0.8) {
      console.log('Near bottom, consider loading more');
    }
  }
  
  onMount(loadItems);
</script>

<div class="list-container">
  <VirtualList
    itemCount={items.length}
    itemSize={getItemHeight}
    estimatedItemSize={70}
    height={800}
    width="100%"
    scrollDirection="vertical"
    overscanCount={5}
    {getKey}
    onItemsUpdated={handleItemsUpdated}
    onAfterScroll={handleScroll}
    stickyIndices={[0]}
  >
    {#snippet item({ index, style })}
      <div {style} class="item" class:selected={index === selectedIndex}>
        <strong>{items[index].title}</strong>
        <p>{items[index].description}</p>
      </div>
    {/snippet}
    
    {#snippet header()}
      <div class="list-header">My Items</div>
    {/snippet}
    
    {#snippet footer()}
      <InfiniteLoading on:infinite={loadMore} />
    {/snippet}
  </VirtualList>
</div>

<style>
  :global(.virtual-list-wrapper) {
    border: 1px solid #ddd;
  }
  
  :global(.item) {
    padding: 10px;
    border-bottom: 1px solid #eee;
    cursor: pointer;
  }
  
  :global(.item.selected) {
    background: #e3f2fd;
  }
</style>
```

--------------------------------

### Core Architecture Layers

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/architecture.md

Illustrates the three-layer architecture of the svelte-tiny-virtual-list component, showing the interaction between the Svelte component, the SizeAndPositionManager, and constants/type definitions.

```text
┌─────────────────────────────────────────────────────────┐
│  VirtualList Component (Svelte)                         │
│  - Props, snippets, event handlers                      │
│  - Scrolling and reflow logic                           │
└────────────────┬────────────────────────────────────────┘
                 │
┌────────────────┴────────────────────────────────────────┐
│  SizeAndPositionManager (JavaScript Class)              │
│  - Size and offset calculations                         │
│  - Caching and memoization                              │
│  - Search algorithms (binary, exponential)              │
└────────────────┬────────────────────────────────────────┘
                 │
┌────────────────┴────────────────────────────────────────┐
│  Constants and Type Definitions                         │
│  - Alignment, Direction, ScrollChangeReason            │
│  - TypeScript type definitions for consumer API         │
└─────────────────────────────────────────────────────────┘
```

--------------------------------

### VirtualList onItemsUpdated Event Handler

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/VirtualList.md

Callback function executed when the visible items in the VirtualList change. It receives the start and end indices of the currently visible items.

```javascript
onItemsUpdated={({ start, end }) => {
  console.log(`Visible items: ${start} to ${end}`);
}}
```

--------------------------------

### VirtualList with Scroll to Index and Alignment

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/VirtualList.md

Demonstrates controlling the scroll position using `scrollToIndex` and `scrollToAlignment`. This is useful for navigating to specific items programmatically.

```svelte
<script>
  import VirtualList from 'svelte-tiny-virtual-list';

  let items = Array.from({ length: 1000 }, (_, i) => `Item ${i + 1}`);
  let itemCount = items.length;
  let itemSize = 50;

  let listInstance;
  let targetIndex = 50;
  let alignment = 'center'; // 'start', 'center', 'end', 'auto'
  let behaviour = 'smooth'; // 'smooth', 'instant', 'auto'
</script>

<VirtualList
  bind:this={listInstance}
  width={300}
  height={400}
  itemCount={itemCount}
  itemSize={itemSize}
  scrollToIndex={targetIndex}
  scrollToAlignment={alignment}
  scrollToBehaviour={behaviour}
>
  {#snippet item({ index, style })}
    <div style={style} class="item">
      {items[index]}
    </div>
  {/snippet}
</VirtualList>

<style>
  .item {
    padding: 10px;
    border-bottom: 1px solid #eee;
  }
</style>

<button on:click={() => listInstance.scrollToIndex(50, 'center', 'smooth')}>Scroll to Item 50 (Center, Smooth)</button>
```

--------------------------------

### resetItem

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/SizeAndPositionManager.md

Clears cached size and position data for items starting from a specified index. This is essential when item sizes change dynamically, ensuring accurate recalculations.

```APIDOC
## resetItem(index)

### Description
Clears cached size and position data for items at and after the specified index. Used when item sizes change dynamically.

### Parameters
#### Path Parameters
- **index** (number) - Required - The starting index from which to clear cache.

### Returns
`void`

### Note
This method does not immediately recalculate; calculations are performed lazily the next time sizes are requested.

### Example
```javascript
const manager = new SizeAndPositionManager(
  (index) => data[index].height,
  data.length,
  50
);
// After data changes:
manager.resetItem(0); // Clear cache from start
```
```

--------------------------------

### getUpdatedOffsetForIndex

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/SizeAndPositionManager.md

Calculates the necessary scroll offset to bring a target item into view with a specified alignment (e.g., start, center, end). This is used for programmatic scrolling.

```APIDOC
## getUpdatedOffsetForIndex(align, containerSize, currentOffset, targetIndex)

### Description
Calculates the scroll offset required to bring a specific item into view with the desired alignment.

### Parameters
#### Path Parameters
- **align** ('auto' | 'start' | 'center' | 'end') - Required - Desired alignment: `'start'` (top/left), `'center'` (middle), `'end'` (bottom/right), or `'auto'` (scroll minimum distance).
- **containerSize** (number) - Required - Height or width of the visible viewport (in pixels).
- **currentOffset** (number) - Required - The current scroll position (in pixels).
- **targetIndex** (number) - Required - The index of the item to scroll to.

### Returns
`number` - The scroll offset to use.

### Example
```javascript
const manager = new SizeAndPositionManager(50, 1000, 50);
const offset = manager.getUpdatedOffsetForIndex('center', 600, 1200, 500);
wrapper.scrollTop = offset; // Scroll to item 500, centered
```
```

--------------------------------

### Module Organization

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/architecture.md

Defines the file structure of the svelte-tiny-virtual-list library.

```tree
src/lib/
├── VirtualList.svelte          Main component (Svelte 5)
├── SizeAndPositionManager.js    Size/position calculation engine
├── constants.js                 Direction, alignment, scroll constants
├── types.d.ts                   TypeScript definitions
├── index.ts                     Public API entry point
└── index.js                     Compiled JavaScript export
```

--------------------------------

### Overscan Buffering Logic

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/architecture.md

Adjusts the start and end indices to include a buffer of items beyond the visible range, smoothing scroll transitions. Ensure `overscanCount` is provided.

```javascript
if (overscanCount) {
  start = Math.max(0, start - overscanCount);
  end = Math.min(end + overscanCount, itemCount - 1);
}
```

--------------------------------

### Initialize SizeAndPositionManager with Fixed Size

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/SizeAndPositionManager.md

Use this snippet to initialize the SizeAndPositionManager when all items have a uniform size. This is the most performant option.

```javascript
const manager = new SizeAndPositionManager(50, 1000, 50);
```

--------------------------------

### Calculate Scroll Offset for Item Alignment

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/SizeAndPositionManager.md

Calculates the necessary scroll offset to bring a target item into view with a specified alignment ('start', 'center', 'end', or 'auto').

```javascript
const manager = new SizeAndPositionManager(50, 1000, 50);
const offset = manager.getUpdatedOffsetForIndex('center', 600, 1200, 500);
wrapper.scrollTop = offset; // Scroll to item 500, centered
```

--------------------------------

### Configure Fixed Item Size

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/configuration.md

Use this for the fastest performance when all items in the list have the same dimensions. Pre-computes sizes during initialization.

```svelte
<VirtualList itemSize={50} itemCount={1000} />
```

--------------------------------

### Configure Dynamic Item Size Function

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/configuration.md

Best for very large lists with varied item sizes, offering memory efficiency. Sizes are calculated just-in-time using a provided function.

```svelte
<VirtualList
  itemSize={(index) => data[index].height}
  itemCount={1000}
  estimatedItemSize={50}
/>
```

--------------------------------

### Calculate Visible Item Range

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/SizeAndPositionManager.md

Determines the start and end indices of items that should be rendered based on the current scroll position and container size. Includes overscan for smooth scrolling.

```javascript
const manager = new SizeAndPositionManager(50, 1000, 50);
const { start, end } = manager.getVisibleRange(600, 1200, 3);
console.log(`Render items ${start} through ${end}`);
```

--------------------------------

### VirtualList with Sticky Indices

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/VirtualList.md

Shows how to make specific items sticky using the `stickyIndices` prop. Sticky items remain visible when scrolling past them, useful for headers or separators.

```svelte
<script>
  import VirtualList from 'svelte-tiny-virtual-list';

  let items = Array.from({ length: 100 }, (_, i) => `Item ${i + 1}`);
  let itemCount = items.length;
  let itemSize = 50;
  let stickyIndices = [0, 10, 20]; // Make items 0, 10, and 20 sticky
</script>

<VirtualList
  width={300}
  height={400}
  itemCount={itemCount}
  itemSize={itemSize}
  stickyIndices={stickyIndices}
>
  {#snippet item({ index, style })}
    <div style={style} class="item {
      stickyIndices.includes(index) ? 'sticky-item' : ''
    }">
      {items[index]}
    </div>
  {/snippet}
</VirtualList>

<style>
  .item {
    padding: 10px;
    border-bottom: 1px solid #eee;
  }
  .sticky-item {
    position: sticky;
    top: 0;
    background-color: #f0f0f0;
    font-weight: bold;
    z-index: 1;
  }
</style>
```

--------------------------------

### Reset Item Cache for Dynamic Sizing

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/api-reference/SizeAndPositionManager.md

Clears cached size and position data for items starting from a given index. This is essential when item sizes change dynamically after initial measurement.

```javascript
const manager = new SizeAndPositionManager(
  (index) => data[index].height,
  data.length,
  50
);
// After data changes:
manager.resetItem(0); // Clear cache from start
```

--------------------------------

### Virtual List with Dynamic Keys

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/QUICK_START.md

Utilizes the `getKey` prop to provide unique keys for list items, which is crucial for efficient updates when the data changes.

```svelte
<script>
  let users = $state([
    { id: 'u1', name: 'Alice' },
    { id: 'u2', name: 'Bob' },
  ]);

  function getKey(index) {
    return users[index].id;
  }
</script>

<VirtualList
  itemCount={users.length}
  itemSize={50}
  height={600}
  width="100%"
  {getKey}
>
  {#snippet item({ style, index })}
    <div {style}>{users[index].name}</div>
  {/snippet}
</VirtualList>
```

--------------------------------

### ItemSizeGetter

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/types.md

A function type that defines how to get the size (height or width) of an item at a specific index. It takes the item's index as a number and should return its size in pixels, which must be a positive number.

```APIDOC
## ItemSizeGetter

### Description
Function type that returns the size (height or width) of an item at a given index.

### Parameters
#### Path Parameters
- **index** (number) - Required - Zero-based index of the item

### Returns
- **number** - Size in pixels (must be positive)

### Example
```typescript
const getItemSize: ItemSizeGetter = (index) => {
  return 50 + (index % 2) * 10; // Alternate between 50px and 60px
};

const getItemSizeFromData: ItemSizeGetter = (index) => {
  return items[index].displayHeight;
};
```
```

--------------------------------

### Package.json Configuration for Svelte and Types

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/EXPORTS.md

Shows the package.json configuration that specifies the main Svelte component entry point and the TypeScript definition file location.

```json
{
  "svelte": "./dist/index.js",
  "types": "./dist/index.d.ts"
}
```

--------------------------------

### Source Code Hierarchy

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/architecture.md

Illustrates the import and export relationships between the main files in the svelte-tiny-virtual-list project. Highlights the public entry point and core modules.

```text
index.ts (public entry point)
  ↓ re-exports
VirtualList.svelte
  ├─ imports → SizeAndPositionManager.js
  ├─ imports → constants.js
  └─ uses types from → types.d.ts

SizeAndPositionManager.js
  └─ imports → constants.js
```

--------------------------------

### Constants

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/DELIVERY_SUMMARY.txt

Documentation for constants used within the svelte-tiny-virtual-list library.

```APIDOC
## Constants

### Description

This section lists the constants used throughout the `svelte-tiny-virtual-list` library.

### `DEFAULT_ITEM_HEIGHT`

- **Type**: `number`
- **Value**: `40`
- **Description**: The default height in pixels for list items when not explicitly specified.

### `DEFAULT_OVERSCAN`

- **Type**: `number`
- **Value**: `3`
- **Description**: The default number of items to render above and below the visible viewport for smooth scrolling.

### `DEFAULT_ESTIMATED_ITEM_SIZE`

- **Type**: `number`
- **Value**: `50`
- **Description**: The default estimated item size used by `SizeAndPositionManager` for initial calculations when item heights might not be immediately known.
```

--------------------------------

### List with Variable Item Heights

Source: https://github.com/jonasgeiler/svelte-tiny-virtual-list/blob/main/_autodocs/QUICK_START.md

Demonstrates a virtual list where items have different heights. Uses a function for itemSize and provides estimatedItemSize for performance.

```svelte
<script>
  const items = [
    { id: 1, text: 'Short item', height: 40 },
    { id: 2, text: 'Much longer item that spans multiple lines', height: 80 },
  ];

  function getItemSize(index) {
    return items[index].height;
  }
</script>

<VirtualList
  width="100%"
  height={600}
  itemCount={items.length}
  itemSize={getItemSize}
  estimatedItemSize={50}
>
  {#snippet item({ style, index })}
    <div {style}>{items[index].text}</div>
  {/snippet}
</VirtualList>
```