Velocity-Based Loading

// Velocity-Based Loading - Pure Vanilla JavaScript
// Demonstrates smart loading that adapts to scroll velocity

import {
  vlist,
  withSelection,
  withAsync,
  withScale,
  withScrollbar,
  withSnapshots,
} from "vlist";
import {
  CANCEL_LOAD_VELOCITY_THRESHOLD,
  TOTAL_ITEMS,
  ITEM_HEIGHT,
  fetchItems,
  itemTemplate,
  setApiDelay,
  setUseRealApi,
  getUseRealApi,
  formatApiSource,
  formatVelocity,
  formatLoadedCount,
} from "../shared.js";

// Storage key for snapshots
const STORAGE_KEY = "vlist-velocity-loading-snapshot";

// Parse saved snapshot (if any) to configure autoLoad + restore
const savedRaw = sessionStorage.getItem(STORAGE_KEY);
let snapshot = undefined;
if (savedRaw) {
  try {
    snapshot = JSON.parse(savedRaw);
  } catch (e) {
    // Corrupt data — ignore
  }
}

// Stats tracking
let loadRequests = 0;
let loadedCount = 0;
let currentVelocity = 0;
let currentScrollTop = 0;
let isLoading = false;
let saveSnapshotTimeoutId = null;
let isRestoringSnapshot = !!snapshot;

// DOM references (will be set after DOM loads)
let statRequestsEl, statLoadedEl, statVelocityEl, statScrollTopEl;
let loadRequestsEl, loadedCountEl;
let velocityValueEl, velocityFillEl, velocityStatusEl;

let prevState = {
  loadRequests: -1,
  loadedCount: -1,
  isLoading: null,
  isAboveThreshold: null,
  velocityPercent: -1,
};

// Update functions
function updateStatsBar() {
  if (statRequestsEl) statRequestsEl.textContent = loadRequests;
  if (statLoadedEl) statLoadedEl.textContent = formatLoadedCount(loadedCount);
  if (statVelocityEl)
    statVelocityEl.textContent = formatVelocity(currentVelocity);
  if (statScrollTopEl)
    statScrollTopEl.textContent = Math.round(currentScrollTop).toLocaleString();
}

function updateControls() {
  if (!velocityValueEl) return; // DOM not ready

  const velocityPercent = Math.min(100, (currentVelocity / 30) * 100);
  const isAboveThreshold = currentVelocity > CANCEL_LOAD_VELOCITY_THRESHOLD;

  if (prevState.loadRequests !== loadRequests) {
    loadRequestsEl.textContent = loadRequests;
    prevState.loadRequests = loadRequests;
  }

  if (prevState.loadedCount !== loadedCount) {
    loadedCountEl.textContent = formatLoadedCount(loadedCount);
    prevState.loadedCount = loadedCount;
  }

  if (prevState.isAboveThreshold !== isAboveThreshold) {
    if (isAboveThreshold) {
      velocityValueEl.parentElement.classList.add("velocity-display--fast");
      velocityFillEl.classList.add("velocity-bar__fill--fast");
      velocityFillEl.classList.remove("velocity-bar__fill--slow");
      velocityStatusEl.classList.add("velocity-status--skipped");
      velocityStatusEl.classList.remove("velocity-status--allowed");
      velocityStatusEl.textContent = "🚫 Loading skipped";
    } else {
      velocityValueEl.parentElement.classList.remove("velocity-display--fast");
      velocityFillEl.classList.remove("velocity-bar__fill--fast");
      velocityFillEl.classList.add("velocity-bar__fill--slow");
      velocityStatusEl.classList.remove("velocity-status--skipped");
      velocityStatusEl.classList.add("velocity-status--allowed");
      velocityStatusEl.textContent = "✅ Loading allowed";
    }
    prevState.isAboveThreshold = isAboveThreshold;
  }

  velocityValueEl.textContent = formatVelocity(currentVelocity);

  const roundedPercent = Math.round(velocityPercent);
  if (prevState.velocityPercent !== roundedPercent) {
    velocityFillEl.style.width = `${roundedPercent}%`;
    prevState.velocityPercent = roundedPercent;
  }
}

// Build list — snapshot restoration happens automatically via withSnapshots({ restore })
// before the browser's first paint, so the user never sees position 0.
const list = vlist({
  container: "#list-container",
  ariaLabel: "Virtual user list with velocity-based loading",
  item: {
    height: ITEM_HEIGHT,
    template: itemTemplate,
  },
})
  .use(withSelection({ mode: "single" }))
  .use(
    withAsync({
      adapter: {
        read: async ({ offset, limit }) => {
          loadRequests++;
          isLoading = true;
          updateControls();
          updateStatsBar();
          const result = await fetchItems(offset, limit);
          isLoading = false;
          updateControls();
          updateStatsBar();
          return result;
        },
      },
      autoLoad: !snapshot,
      total: snapshot?.total,
      storage: {
        chunkSize: 25,
      },
      loading: {
        cancelThreshold: CANCEL_LOAD_VELOCITY_THRESHOLD,
      },
    }),
  )
  .use(withScale())
  .use(withScrollbar({ autoHide: true }))
  .use(withSnapshots({ restore: snapshot }))
  .build();

// Get DOM references
statRequestsEl = document.getElementById("stat-requests");
statLoadedEl = document.getElementById("stat-loaded");
statVelocityEl = document.getElementById("stat-velocity");
statScrollTopEl = document.getElementById("stat-scrolltop");
loadRequestsEl = document.getElementById("load-requests");
loadedCountEl = document.getElementById("loaded-count");
velocityValueEl = document.getElementById("velocity-value");
velocityFillEl = document.getElementById("velocity-fill");
velocityStatusEl = document.getElementById("velocity-status");

const btnSimulated = document.getElementById("btn-simulated");
const btnLiveApi = document.getElementById("btn-live-api");
const sliderDelay = document.getElementById("slider-delay");
const delayValueEl = document.getElementById("delay-value");
const btnStart = document.getElementById("btn-start");
const btnMiddle = document.getElementById("btn-middle");
const btnEnd = document.getElementById("btn-end");
const btnReload = document.getElementById("btn-reload");
const btnResetStats = document.getElementById("btn-reset-stats");

// Auto-save snapshot when scroll becomes idle
function scheduleSaveSnapshot() {
  if (isRestoringSnapshot) return;

  if (saveSnapshotTimeoutId) {
    clearTimeout(saveSnapshotTimeoutId);
  }
  saveSnapshotTimeoutId = setTimeout(() => {
    const snap = list.getScrollSnapshot();
    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(snap));
    saveSnapshotTimeoutId = null;
  }, 500);
}

// Event bindings
list.on("scroll", ({ scrollTop }) => {
  currentScrollTop = scrollTop;
  updateStatsBar();
  scheduleSaveSnapshot();
});

list.on("velocity:change", ({ velocity }) => {
  currentVelocity = velocity;
  updateControls();
  updateStatsBar();
});

list.on("load:start", () => {
  isLoading = true;
  updateControls();
  updateStatsBar();
});

list.on("load:end", ({ items }) => {
  isLoading = false;
  loadedCount += items.length;
  updateControls();
  updateStatsBar();
});

list.on("selection:change", () => {
  scheduleSaveSnapshot();
});

// Re-enable saving after restore settles
if (isRestoringSnapshot) {
  setTimeout(() => {
    isRestoringSnapshot = false;
  }, 2000);
}

// Update button states
function updateDataSourceButtons() {
  const useRealApi = getUseRealApi();
  if (useRealApi) {
    btnSimulated.classList.remove("panel-btn--active");
    btnLiveApi.classList.add("panel-btn--active");
  } else {
    btnSimulated.classList.add("panel-btn--active");
    btnLiveApi.classList.remove("panel-btn--active");
  }
}

// Controls
btnSimulated.addEventListener("click", async () => {
  if (!getUseRealApi()) return; // Already simulated
  setUseRealApi(false);
  updateDataSourceButtons();
  loadedCount = 0;
  prevState.loadedCount = -1;
  updateControls();
  updateStatsBar();
  await list.reload();
});

btnLiveApi.addEventListener("click", async () => {
  if (getUseRealApi()) return; // Already live
  setUseRealApi(true);
  updateDataSourceButtons();
  loadedCount = 0;
  prevState.loadedCount = -1;
  updateControls();
  updateStatsBar();
  await list.reload();
});

sliderDelay.addEventListener("input", () => {
  const delay = parseInt(sliderDelay.value, 10);
  setApiDelay(delay);
  delayValueEl.textContent = `${delay}ms`;
});

btnStart.addEventListener("click", () => {
  list.scrollToIndex(0, {
    align: "start",
    behavior: "smooth",
  });
});

btnMiddle.addEventListener("click", () => {
  const middle = Math.floor(TOTAL_ITEMS / 2);
  list.scrollToIndex(middle, {
    align: "center",
    behavior: "smooth",
  });
});

btnEnd.addEventListener("click", () => {
  list.scrollToIndex(TOTAL_ITEMS - 1, {
    align: "end",
    behavior: "smooth",
  });
});

btnReload.addEventListener("click", async () => {
  loadedCount = 0;
  prevState.loadedCount = -1;
  updateControls();
  updateStatsBar();
  await list.reload();
});

btnResetStats.addEventListener("click", () => {
  loadRequests = 0;
  loadedCount = 0;
  prevState.loadRequests = -1;
  prevState.loadedCount = -1;
  updateControls();
  updateStatsBar();
});

// Initial update
updateDataSourceButtons();
updateControls();
updateStatsBar();

<div class="container">
    <header>
        <h1>Velocity-Based Loading</h1>
        <p class="description">
            Pure vanilla JavaScript. Smart data loading that skips fetching when scrolling fast (&gt;15 px/ms)
            and loads immediately when velocity drops. Handling 1,000,000 items with adaptive loading.
        </p>
    </header>

    <div class="stats" id="stats">
        <span></span><strong>Requests:</strong> <span id="stat-requests">0</span></span>
        <span><strong>Loaded:</strong> <span id="stat-loaded">0</span></span>
        <span><strong>Velocity:</strong> <span id="stat-velocity">0.0</span> px/ms</span>
        <span><strong>ScrollTop:</strong> <span id="stat-scrolltop">0</span> px</span>
    </div>

    <div class="split-layout">
        <div class="split-main">
            <div id="list-container"></div>
        </div>

        <aside class="split-panel">
            <!-- Loading Stats -->
            <section class="panel-section">
                <h3 class="panel-title">Loading Stats</h3>
                <div class="stats-grid">
                    <div class="stat-card">
                        <div id="load-requests" class="stat-card__value">0</div>
                        <div class="stat-card__label">Requests</div>
                    </div>
                    <div class="stat-card">
                        <div id="loaded-count" class="stat-card__value">0</div>
                        <div class="stat-card__label">Loaded</div>
                    </div>
                </div>
            </section>

            <!-- Velocity Display -->
            <section class="panel-section">
                <h3 class="panel-section__title">Scroll Velocity</h3>
                <div class="velocity-display">
                    <span id="velocity-value" class="velocity-display__value">0.0</span>
                    <span class="velocity-display__unit">px/ms</span>
                </div>
                <div class="velocity-bar">
                    <div id="velocity-fill" class="velocity-bar__fill"></div>
                    <div class="velocity-bar__marker"></div>
                </div>
                <div class="velocity-labels">
                    <span>0</span>
                    <span class="velocity-labels__threshold">15</span>
                    <span>30+</span>
                </div>
                <div id="velocity-status" class="velocity-status velocity-status--allowed">
                    ✅ Loading allowed
                </div>
            </section>

            <!-- Data Source -->
            <section class="panel-section">
                <h3 class="panel-title">Data Source</h3>
                <div class="panel-btn-group">
                    <button id="btn-simulated" class="panel-btn">
                        🧪 Simulated
                    </button>
                    <button id="btn-live-api" class="panel-btn">
                        ⚡ Live API
                    </button>
                </div>
            </section>

            <!-- API Delay -->
            <section class="panel-section">
                <div class="panel-row">
                    <label class="panel-label" for="slider-delay">
                        API Delay
                        <span id="delay-value" class="panel-value">0ms</span>
                    </label>
                    <input id="slider-delay" type="range" class="panel-slider" min="0" max="1000" step="20" value="0">
                </div>
            </section>



            <!-- Navigation -->
            <section class="panel-section">
                <h3 class="panel-title">Navigation</h3>
                <div class="panel-btn-group">
                    <button id="btn-start" class="panel-btn">Start</button>
                    <button id="btn-middle" class="panel-btn">Middle</button>
                    <button id="btn-end" class="panel-btn">End</button>
                </div>
            </section>

            <!-- Actions -->
            <section class="panel-section">
                <h3 class="panel-title">Actions</h3>
                <div class="panel-btn-group">
                    <button id="btn-reload" class="panel-btn">Reload</button>
                    <button id="btn-reset-stats" class="panel-btn">Reset Stats</button>
                </div>
            </section>
        </aside>
    </div>

    <footer>
        <p>
            Velocity-based loading prevents API spam during fast scrolling while ensuring data loads when you slow down. ⚡
        </p>
    </footer>
</div>

// Shared data and utilities for velocity-loading example variants
// This file is imported by all framework implementations to avoid duplication

// =============================================================================
// Constants
// =============================================================================

export const CANCEL_LOAD_VELOCITY_THRESHOLD = 15; // px/ms
export const TOTAL_ITEMS = 1000000;
export const API_BASE = "http://localhost:3338";
export const ITEM_HEIGHT = 72;

// =============================================================================
// API State
// =============================================================================

let apiDelay = 0;
let useRealApi = true; // Start with live API by default

export const setApiDelay = (delay) => {
  apiDelay = delay;
};

export const setUseRealApi = (value) => {
  useRealApi = value;
};

export const getUseRealApi = () => useRealApi;

// =============================================================================
// Real API — fetches from vlist.dev backend
// =============================================================================

const fetchFromApi = async (offset, limit) => {
  const params = new URLSearchParams({
    offset: String(offset),
    limit: String(limit),
    total: String(TOTAL_ITEMS),
  });
  if (apiDelay > 0) params.set("delay", String(apiDelay));

  const res = await fetch(`${API_BASE}/api/users?${params}`);
  if (!res.ok) throw new Error(`API error: ${res.status}`);
  return res.json();
};

// =============================================================================
// Simulated API — deterministic in-memory fallback
// =============================================================================

const generateItem = (id) => ({
  id,
  name: `User ${id}`,
  email: `user${id}@example.com`,
  role: ["Admin", "Editor", "Viewer"][id % 3],
  avatar: String.fromCharCode(65 + (id % 26)),
});

const fetchSimulated = async (offset, limit) => {
  if (apiDelay > 0) await new Promise((r) => setTimeout(r, apiDelay));
  const items = [];
  const end = Math.min(offset + limit, TOTAL_ITEMS);
  for (let i = offset; i < end; i++) items.push(generateItem(i + 1));
  return { items, total: TOTAL_ITEMS, hasMore: end < TOTAL_ITEMS };
};

// =============================================================================
// Unified fetch
// =============================================================================

export const fetchItems = (offset, limit) =>
  useRealApi ? fetchFromApi(offset, limit) : fetchSimulated(offset, limit);

// =============================================================================
// Template — single template for both real items and placeholders.
// The renderer adds .vlist-item--placeholder on the wrapper element,
// so CSS handles the visual difference (skeleton blocks, shimmer, etc).
// Placeholder items carry the same fields as real data, filled with
// mask characters (x) sized to match actual data from the first batch.
// =============================================================================

export const itemTemplate = (item, index) => {
  const displayName = item.firstName
    ? `${item.firstName} ${item.lastName}`
    : item.name || "";
  const avatarText = item.avatar || displayName[0] || "";

  return `
    <div class="item-content">
      <div class="item-avatar">${avatarText}</div>
      <div class="item-details">
        <div class="item-name">${displayName} (#${index + 1})</div>
        <div class="item-email">${item.email || ""}</div>
        <div class="item-role">${item.role || ""}</div>
      </div>
    </div>
  `;
};

// =============================================================================
// Utilities
// =============================================================================

export const formatApiSource = (useRealApi) =>
  useRealApi ? "⚡ Live API" : "🧪 Simulated";

export const formatVelocity = (velocity) => velocity.toFixed(1);

export const formatLoadedCount = (count) => count.toLocaleString();

/* Basic Example — example-specific styles only
   Common styles (.container, h1, .description, .stats, footer)
   are provided by example/example.css using shell.css design tokens.
   Panel system (.split-layout, .split-panel, .panel-*)
   is also provided by example/example.css. */

/* List container height */
#list-container {
    height: 600px;
    max-width: 360px;
    margin: 0 auto;
}

/* ============================================================================
   Item Detail — example-specific avatar + email
   ============================================================================ */

.panel-detail__avatar {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    width: 32px;
    height: 32px;
    border-radius: 50%;
    background: #667eea;
    color: white;
    font-weight: 600;
    font-size: 14px;
    flex-shrink: 0;
}

.panel-detail__email {
    font-size: 12px;
    color: var(--text-muted);
}

/* ============================================================================
   Item styles (inside list)
   ============================================================================ */

.item-content {
    display: flex;
    align-items: center;
    gap: 12px;
    padding: 0;
    height: 100%;
}

.item-avatar {
    width: 40px;
    height: 40px;
    border-radius: 50%;
    background: #667eea;
    display: flex;
    align-items: center;
    justify-content: center;
    color: white;
    font-weight: 600;
    font-size: 16px;
    flex-shrink: 0;
}

.item-details {
    flex: 1;
    min-width: 0;
    display: flex;
    flex-direction: column;
    justify-content: center;
}

.item-name {
    font-weight: 500;
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
}

.item-email {
    font-size: 12px;
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
}

.item-role {
    font-size: 12px;
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
}

.item-index {
    font-size: 12px;
    min-width: 60px;
    text-align: right;
}

/* ============================================================================
   Placeholder skeleton — driven by .vlist-item--placeholder on the wrapper.
   The template is identical for real and placeholder items; mask characters
   (x) set the natural width, CSS hides them and shows skeleton blocks.
   ============================================================================ */

.vlist-item--placeholder .item-avatar {
    background-color: rgba(102, 126, 234, 0.9);
    color: transparent;
}

.vlist-item--placeholder .item-name {
    color: transparent;
    background-color: var(--vlist-placeholder-bg);
    border-radius: 4px;
    width: fit-content;
    min-width: 60%;
    line-height: 1.1;
    margin-bottom: 1px;
}

.vlist-item--placeholder .item-email {
    color: transparent;
    background-color: var(--vlist-placeholder-bg);
    border-radius: 4px;
    width: fit-content;
    min-width: 70%;
    line-height: 1;
    margin-bottom: 1px;
}

.vlist-item--placeholder .item-role {
    color: transparent;
    background-color: var(--vlist-placeholder-bg);
    border-radius: 4px;
    width: fit-content;
    min-width: 30%;
    line-height: 1;
}

/* ============================================================================
   Velocity-specific styles
   ============================================================================ */

.stats-grid {
    display: grid;
    grid-template-columns: repeat(2, 1fr);
    gap: 12px;
}

.stat-card {
    padding: 4px;
    background: var(--surface-container);
    border-radius: 12px;
    text-align: center;
}

.stat-card__value {
    font-size: 20px;
    font-weight: 700;
    color: var(--text-primary);
}

.stat-card__value--loading {
    color: #667eea;
}

.stat-card__value--idle {
    color: #43e97b;
}

.stat-card__label {
    font-size: 12px;
    color: var(--text-muted);
    text-transform: uppercase;
    letter-spacing: 0.5px;
}

.panel-section__title {
    font-size: 14px;
    font-weight: 600;
    margin-bottom: 12px;
}

.velocity-display {
    display: flex;
    align-items: baseline;
    justify-content: center;
    gap: 4px;
    margin-bottom: 4px;
    padding: 4px;
    background: var(--surface-container);
    border-radius: 12px;
    transition: background 0.2s ease;
}

.velocity-display--fast {
    background: color-mix(in srgb, #fa709a 10%, transparent);
}

.velocity-display__value {
    font-size: 24px;
    font-weight: 700;
    font-variant-numeric: tabular-nums;
}

.velocity-display__unit {
    font-size: 16px;
    color: var(--text-muted);
    font-weight: 500;
}

.velocity-bar {
    position: relative;
    height: 16px;
    background: var(--surface-container);
    border-radius: 8px;
    overflow: hidden;
    margin-bottom: 8px;
}

.velocity-bar__fill {
    height: 100%;
    background: linear-gradient(90deg, #43e97b, #667eea);
    transition:
        width 0.3s ease,
        background 0.2s ease;
    border-radius: 8px;
    width: 0%;
}

.velocity-bar__fill--fast {
    background: linear-gradient(90deg, #667eea, #fa709a);
}

.velocity-bar__fill--slow {
    background: linear-gradient(90deg, #43e97b, #667eea);
}

.velocity-bar__marker {
    position: absolute;
    left: 50%;
    top: 0;
    bottom: 0;
    width: 2px;
    background: var(--outline-variant, rgba(0, 0, 0, 0.3));
}

.velocity-labels {
    display: flex;
    justify-content: space-between;
    font-size: 11px;
    color: var(--text-muted);
    margin-bottom: 12px;
}

.velocity-labels__threshold {
    font-weight: 600;
}

.velocity-status {
    padding: 12px 16px;
    border-radius: 8px;
    text-align: center;
    font-weight: 600;
    font-size: 14px;
    transition: all 0.2s ease;
}

.velocity-status--allowed {
    background: color-mix(in srgb, #43e97b 10%, transparent);
    color: var(--color-success, #2ea563);
}

.velocity-status--skipped {
    background: color-mix(in srgb, #fa709a 10%, transparent);
    color: var(--color-error, #d63c6f);
}

/* ============================================================================
   Button Group Enhancement
   ============================================================================ */

.panel-btn-group {
    display: flex;
    gap: 8px;
    background: var(--surface-container);
    padding: 4px;
    border-radius: 12px;
}

.panel-btn-group .panel-btn {
    flex: 1;
    background: transparent;
    border: none;
    color: var(--text-secondary);
    transition: all 0.2s ease;
    font-weight: 500;
}

.panel-btn-group .panel-btn:hover {
    background: var(--surface-container-high);
    color: var(--text-primary);
}

.panel-btn-group .panel-btn--active {
    background: var(--surface-container-highest);
    color: var(--text-primary);
    font-weight: 600;
    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

.panel-btn-group .panel-btn--active:hover {
    background: var(--surface-container-highest);
}

/* ============================================================================
   Responsive
   ============================================================================ */

@media (max-width: 820px) {
    #list-container {
        max-width: none;
        height: 400px;
    }
}