@yewdiel21/motion-kit 0.10.0 → 0.15.0

package/src/components/virtual-list/engine.ts

@@ -0,0 +1,678 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { requestFrame } from '../../core/frame';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { fromJson } from '../../core/dates';
+import { createSizes, type VirtualRange } from '../../core/virtual';
+import { blurIn } from '../../motion/micro';
+
+/*
+ * Virtual list: thousands of rows with only those in view (and a few around
+ * them) in the page. Rows are recycled as they scroll; their heights are one
+ * fixed value or measured as they show (an estimate for the rest), and the
+ * scroll stays put when a measured row above changes size. While scrolling, a
+ * pill rides the right edge with the position ("1 240 de 10 000") and slips
+ * away out of a blur when the scroll stops. scrollToIndex() glides there
+ * (.6 s, signature; a long way jumps most of it first) and flashes the row.
+ * Selectable lists are a listbox: a ring glides between rows with the
+ * keyboard (↑ ↓, Re Pág / Av Pág, Inicio, Fin, typing jumps), and a chosen
+ * row's check pops. onEndReached() brings more rows at the end (a loading row
+ * meanwhile, "No hay más elementos" when it answers with none). The first rows
+ * come in out of a blur; new data flows in softly.
+ */
+
+export type VirtualKey = string | number;
+
+export interface VirtualListOptions<T = unknown> {
+  items?: T[];
+  /** Every row this tall (fastest); without it rows are measured. */
+  itemHeight?: number;
+  /** Height of a row not measured yet (default: itemHeight, else 48). */
+  estimatedHeight?: number;
+  /** Rows drawn beyond each edge (default 6). */
+  overscan?: number;
+  /** Draw a row into its element (recycled: draw all of it every time). Default: its text. */
+  renderItem?: (item: T, index: number, element: HTMLElement) => void;
+  /** A row's text: the default drawing, typing to jump and announcements (default: label, title, name or the value). */
+  itemText?: (item: T) => string;
+  /** A stable key for a row (default: its id, else its index). */
+  getKey?: (item: T, index: number) => VirtualKey;
+  /** Rows can be chosen: true or 'single', or 'multiple' (default false). */
+  selectable?: boolean | 'single' | 'multiple';
+  selected?: VirtualKey[];
+  /** Accessible name (default 'Lista'). */
+  label?: string;
+  emptyLabel?: string;
+  locale?: string;
+  onSelect?: (keys: VirtualKey[], items: T[]) => void;
+  /** Enter or a double click on a row. */
+  onActivate?: (item: T, index: number) => void;
+  /** More rows at the end: resolve with them, with [] when there are no more, or with nothing when you add them yourself (setItems). */
+  onEndReached?: () => Promise<T[] | void> | T[] | void;
+  /** Draw the rows yourself (frameworks): told which ones; put them in `container` as [data-mk-vl-item][data-index] and call refresh(). */
+  onRange?: (range: VirtualRange) => void;
+}
+
+export interface VirtualScrollOptions {
+  align?: 'auto' | 'start' | 'center' | 'end';
+  animate?: boolean;
+}
+
+export interface VirtualListInstance<T = unknown> extends Instance {
+  setItems(items: T[]): void;
+  /** Add rows at the end. */
+  append(items: T[]): void;
+  scrollToIndex(index: number, options?: VirtualScrollOptions): void;
+  /** Position and measure the drawn rows again (after drawing them yourself, or when their content changed). */
+  refresh(): void;
+  select(keys: VirtualKey[]): void;
+  /** Change how rows are drawn (vanilla). */
+  setRenderer(renderItem: (item: T, index: number, element: HTMLElement) => void): void;
+  readonly items: T[];
+  readonly range: VirtualRange;
+  readonly selected: VirtualKey[];
+  /** Where the rows live. */
+  readonly container: HTMLElement;
+}
+
+const FOOT_HEIGHT = 48;
+let sequence = 0;
+
+/** label, title, name or text of an object; the value itself otherwise. */
+const defaultText = (item: unknown): string => {
+  if (item === null || item === undefined) return '';
+  if (typeof item !== 'object') return String(item);
+  const record = item as Record<string, unknown>;
+  const text = record.label ?? record.title ?? record.name ?? record.text;
+  return text === undefined ? JSON.stringify(item) : String(text);
+};
+
+export function createVirtualList<T = unknown>(root: HTMLElement | null, options: VirtualListOptions<T> = {}): VirtualListInstance<T> {
+  if (!root) {
+    return inert({
+      setItems() {}, append() {}, scrollToIndex() {}, refresh() {}, select() {}, setRenderer() {},
+      items: [] as T[], range: { start: 0, end: 0 }, selected: [], container: null as unknown as HTMLElement,
+    });
+  }
+  registerMotion();
+  const scope = createScope();
+  const uid = `mk-vl-${++sequence}`;
+  const locale = options.locale ?? root.closest('[lang]')?.getAttribute('lang') ?? 'es';
+  // A framework may render the viewport and the spacer itself (and the rows inside, see onRange).
+  const adopted = root.querySelector<HTMLElement>(':scope > [data-mk-vl-viewport]');
+  // Rows written as a list inside the root are its text rows.
+  const authored = [...root.querySelectorAll(':scope > ul > li, :scope > ol > li')].map((li) => li.textContent?.trim() ?? '') as T[];
+  // JSON text too (data-mk-items through autoInit).
+  let items: T[] = [...(fromJson(options.items) ?? authored)];
+  const fixed = options.itemHeight && options.itemHeight > 0 ? options.itemHeight : null;
+  const estimate = options.estimatedHeight ?? fixed ?? 48;
+  const overscan = Math.max(0, options.overscan ?? 6);
+  let renderItem = options.renderItem;
+  const external = Boolean(options.onRange) && !renderItem;
+  const selectable = options.selectable === true ? 'single' : options.selectable || null;
+  const keyOf = (item: T, index: number): VirtualKey => {
+    if (options.getKey) return options.getKey(item, index);
+    const id = item && typeof item === 'object' ? (item as { id?: unknown }).id : undefined;
+    return typeof id === 'string' || typeof id === 'number' ? id : index;
+  };
+  const textOf = (item: T) => options.itemText?.(item) ?? defaultText(item);
+  const measured = new Map<VirtualKey, number>();
+  const heights = () => items.map((item, i) => fixed ?? measured.get(keyOf(item, i)) ?? estimate);
+  let sizes = createSizes(heights());
+  let selected = new Set<VirtualKey>(fromJson(options.selected) ?? []);
+  let active = -1;
+  let anchor = -1;
+  let range: VirtualRange = { start: 0, end: 0 };
+  let number: Intl.NumberFormat;
+  try {
+    number = new Intl.NumberFormat(locale);
+  } catch {
+    number = new Intl.NumberFormat();
+  }
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (animation: gsap.core.Animation | null) => {
+    if (!animation) return;
+    effects.add(animation);
+    // Finished ones leave as new ones arrive: the animation's own onComplete stays untouched.
+    for (const effect of effects) if (effect.totalProgress() === 1) effects.delete(effect);
+  };
+
+  // ── The parts ────────────────────────────────────────────────────────────
+  const holder = document.createElement('div');
+  holder.hidden = true;
+  holder.append(...[...root.childNodes].filter((node) => node !== adopted));
+  const viewport = adopted ?? document.createElement('div');
+  viewport.dataset.mkVlViewport = '';
+  scope.attr(viewport, 'tabindex', '0');
+  scope.attr(viewport, 'role', selectable ? 'listbox' : 'list');
+  scope.attr(viewport, 'aria-label', options.label ?? 'Lista');
+  if (selectable === 'multiple') scope.attr(viewport, 'aria-multiselectable', 'true');
+  const spacer = viewport.querySelector<HTMLElement>(':scope > [data-mk-vl-spacer]') ?? document.createElement('div');
+  spacer.dataset.mkVlSpacer = '';
+  const spacerStyle = spacer.getAttribute('style');
+  const cursor = document.createElement('span');
+  cursor.dataset.mkVlCursor = '';
+  cursor.setAttribute('aria-hidden', 'true');
+  const foot = document.createElement('div');
+  foot.dataset.mkVlFoot = '';
+  foot.setAttribute('role', 'presentation');
+  foot.hidden = true;
+  spacer.prepend(cursor);
+  spacer.append(foot);
+  if (!spacer.parentElement) viewport.append(spacer);
+  const empty = document.createElement('p');
+  empty.dataset.mkVlEmpty = '';
+  empty.textContent = options.emptyLabel ?? 'Sin elementos';
+  const pill = document.createElement('div');
+  pill.dataset.mkVlPill = '';
+  pill.setAttribute('aria-hidden', 'true');
+  pill.hidden = true;
+  const status = document.createElement('span');
+  status.className = 'mk-sr-only';
+  status.setAttribute('role', 'status');
+  if (!adopted) root.append(viewport);
+  root.append(empty, pill, status);
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    gsap.killTweensOf([viewport, cursor, pill]);
+    for (const element of drawn.values()) element.remove();
+    for (const part of [cursor, foot, empty, pill, status]) part.remove();
+    // What the framework rendered stays; only what the engine put on it goes.
+    if (adopted) {
+      viewport.removeAttribute('aria-activedescendant');
+      if (spacerStyle === null) spacer.removeAttribute('style');
+      else spacer.setAttribute('style', spacerStyle);
+    } else viewport.remove();
+    root.append(...holder.childNodes);
+  });
+  scope.attr(root, 'data-mk-ready', '');
+
+  // ── Drawing ──────────────────────────────────────────────────────────────
+  const drawn = new Map<number, HTMLElement>();
+  const pool: HTMLElement[] = [];
+  const shows = new WeakMap<HTMLElement, T>();
+  const observed = new WeakSet<HTMLElement>();
+  let refill = false;
+  let firstPaint = true;
+  let tweening = false;
+  let flashIndex = -1;
+
+  const fill = (element: HTMLElement, item: T, index: number) => {
+    element.replaceChildren();
+    if (renderItem) renderItem(item, index, element);
+    else element.textContent = textOf(item);
+  };
+  const rows = () => [...spacer.querySelectorAll<HTMLElement>(':scope > [data-mk-vl-item]')];
+
+  let told: VirtualRange | null = null;
+  /** Vanilla: recycle the elements of the rows that left for the rows that came. Frameworks: tell them which rows. */
+  const draw = () => {
+    if (external) {
+      if (told?.start === range.start && told.end === range.end) return;
+      told = { ...range };
+      options.onRange?.({ ...range });
+      return;
+    }
+    for (const [index, element] of drawn) {
+      if (index >= range.start && index < range.end && index < items.length) continue;
+      drawn.delete(index);
+      element.remove();
+      pool.push(element);
+    }
+    for (let index = range.start; index < range.end; index++) {
+      const item = items[index]!;
+      let element = drawn.get(index);
+      if (!element) {
+        element = pool.pop() ?? document.createElement('div');
+        element.dataset.mkVlItem = '';
+        drawn.set(index, element);
+        spacer.append(element);
+      }
+      if (refill || element.dataset.index !== String(index) || shows.get(element) !== item) {
+        element.dataset.index = String(index);
+        shows.set(element, item);
+        fill(element, item, index);
+      }
+    }
+    refill = false;
+  };
+
+  let resizeObserver: ResizeObserver | null = null;
+  /** Place the drawn rows, give them their roles and states, and measure them. */
+  const paint = () => {
+    let changed = false;
+    for (const element of rows()) {
+      const index = Number(element.dataset.index);
+      if (!Number.isInteger(index) || index < 0 || index >= items.length) continue;
+      const item = items[index]!;
+      element.id = `${uid}-${index}`;
+      element.setAttribute('role', selectable ? 'option' : 'listitem');
+      element.setAttribute('aria-setsize', String(items.length));
+      element.setAttribute('aria-posinset', String(index + 1));
+      if (selectable) element.setAttribute('aria-selected', String(selected.has(keyOf(item, index))));
+      element.toggleAttribute('data-mk-vl-active', index === active);
+      if (index !== flashIndex) element.removeAttribute('data-mk-vl-flash');
+      if (fixed) element.style.height = `${fixed}px`;
+      else {
+        if (resizeObserver && !observed.has(element)) {
+          observed.add(element);
+          resizeObserver.observe(element);
+        }
+        const height = element.getBoundingClientRect().height;
+        if (height > 0 && sizes.set(index, height)) {
+          measured.set(keyOf(item, index), height);
+          changed = true;
+        }
+      }
+    }
+    // Placed with top: transforms stay free for the rows' own motion (entrances clear them).
+    for (const element of rows()) {
+      const index = Number(element.dataset.index);
+      if (Number.isInteger(index) && index < items.length) element.style.top = `${sizes.offset(index)}px`;
+    }
+    return changed;
+  };
+
+  const viewHeight = () => viewport.clientHeight || estimate * 10;
+  const layoutSpacer = () => {
+    const total = sizes.total();
+    spacer.style.height = `${total + (foot.hidden ? 0 : FOOT_HEIGHT)}px`;
+    foot.style.top = `${total}px`;
+    empty.hidden = items.length > 0 || !foot.hidden;
+  };
+
+  const update = (force = false) => {
+    if (scope.disposed) return;
+    // Measuring rows above the first one in view must not move what is in view.
+    const top = viewport.scrollTop;
+    const first = sizes.indexAt(top);
+    const within = top - sizes.offset(first);
+    const next = sizes.range(top, viewHeight(), overscan);
+    if (force || next.start !== range.start || next.end !== range.end) {
+      range = next;
+      draw();
+    }
+    const changed = paint();
+    layoutSpacer();
+    if (changed) {
+      if (!tweening && items.length && Math.abs(sizes.offset(first) + within - viewport.scrollTop) > 0.5) viewport.scrollTop = sizes.offset(first) + within;
+      // Measured rows may change what is in view.
+      const after = sizes.range(viewport.scrollTop, viewHeight(), overscan);
+      if (after.start !== range.start || after.end !== range.end) {
+        range = after;
+        draw();
+        paint();
+        layoutSpacer();
+      }
+    }
+    placeCursor(false);
+    if (active >= 0) {
+      const element = rows().find((row) => Number(row.dataset.index) === active);
+      if (element) viewport.setAttribute('aria-activedescendant', element.id);
+      else viewport.removeAttribute('aria-activedescendant');
+    }
+    if (firstPaint && rows().length) {
+      firstPaint = false;
+      if (!reduced()) keep(blurIn(rows().slice(0, 16), { from: 'rise', stagger: 0.025, duration: 0.4 }));
+    }
+    reachEnd();
+  };
+  let pending: (() => void) | null = null;
+  const schedule = () => {
+    if (pending) return;
+    pending = requestFrame(() => {
+      pending = null;
+      update();
+    });
+  };
+  scope.add(() => pending?.());
+
+  if (typeof ResizeObserver === 'function') {
+    resizeObserver = scope.observe(new ResizeObserver(() => schedule()));
+    resizeObserver.observe(viewport);
+  }
+
+  // ── The position pill ────────────────────────────────────────────────────
+  let pillTimer: ReturnType<typeof setTimeout> | undefined;
+  const hidePill = () => {
+    if (pill.hidden) return;
+    if (reduced()) {
+      pill.hidden = true;
+      return;
+    }
+    keep(gsap.to(pill, { opacity: 0, x: 8, filter: 'blur(6px)', duration: 0.3, ease: 'power2.in', onComplete: () => void (pill.hidden = true) }));
+  };
+  const showPill = () => {
+    if (items.length < 40 || viewport.scrollHeight <= viewport.clientHeight + 1) return;
+    const first = Math.min(items.length - 1, sizes.indexAt(viewport.scrollTop + 1));
+    pill.textContent = `${number.format(first + 1)} de ${number.format(items.length)}`;
+    const wasHidden = pill.hidden;
+    pill.hidden = false;
+    const max = viewport.scrollHeight - viewport.clientHeight;
+    const room = Math.max(0, viewport.clientHeight - pill.offsetHeight - 16);
+    pill.style.top = `${viewport.offsetTop + 8 + (max > 0 ? viewport.scrollTop / max : 0) * room}px`;
+    if (wasHidden && !reduced()) {
+      gsap.killTweensOf(pill);
+      keep(gsap.fromTo(pill, { opacity: 0, x: 8, filter: 'blur(6px)' }, { opacity: 1, x: 0, filter: 'blur(0px)', duration: 0.25, ease: 'power2.out', clearProps: 'filter' }));
+    } else if (wasHidden) gsap.set(pill, { opacity: 1, x: 0 });
+    else if (Number(gsap.getProperty(pill, 'opacity')) < 1) {
+      gsap.killTweensOf(pill);
+      gsap.set(pill, { opacity: 1, x: 0, filter: 'none' });
+    }
+    clearTimeout(pillTimer);
+    pillTimer = setTimeout(hidePill, 900);
+  };
+  scope.add(() => clearTimeout(pillTimer));
+  scope.on(viewport, 'scroll', () => {
+    schedule();
+    showPill();
+  }, { passive: true });
+
+  // ── Going to a row ───────────────────────────────────────────────────────
+  const flash = (index: number) => {
+    flashIndex = index;
+    const element = rows().find((row) => Number(row.dataset.index) === index);
+    if (!element) return;
+    element.removeAttribute('data-mk-vl-flash');
+    // Restart the highlight.
+    void element.offsetWidth;
+    element.setAttribute('data-mk-vl-flash', '');
+    scope.timeout(() => {
+      if (flashIndex === index) flashIndex = -1;
+      element.removeAttribute('data-mk-vl-flash');
+    }, 1300);
+  };
+  const targetTop = (index: number, align: VirtualScrollOptions['align']) => {
+    const top = sizes.offset(index);
+    const height = sizes.get(index);
+    const view = viewport.clientHeight;
+    const max = Math.max(0, sizes.total() + (foot.hidden ? 0 : FOOT_HEIGHT) - view);
+    let target: number;
+    if (align === 'start') target = top;
+    else if (align === 'end') target = top + height - view;
+    else if (align === 'center') target = top + height / 2 - view / 2;
+    else if (top < viewport.scrollTop) target = top;
+    else if (top + height > viewport.scrollTop + view) target = top + height - view;
+    else target = viewport.scrollTop;
+    return Math.max(0, Math.min(max, target));
+  };
+  const scrollToIndex = (index: number, { align = 'auto', animate = true }: VirtualScrollOptions = {}) => {
+    if (!items.length || scope.disposed) return;
+    const at = Math.max(0, Math.min(items.length - 1, Math.round(index)));
+    gsap.killTweensOf(viewport);
+    tweening = false;
+    const target = targetTop(at, align);
+    const distance = target - viewport.scrollTop;
+    if (!animate || reduced() || Math.abs(distance) < 2) {
+      viewport.scrollTop = target;
+      update();
+      flash(at);
+      return;
+    }
+    // A long way: most of it at once, the last screens gliding.
+    const screen = viewport.clientHeight || estimate * 10;
+    if (Math.abs(distance) > screen * 3) {
+      viewport.scrollTop = target - Math.sign(distance) * screen * 2;
+      update();
+    }
+    tweening = true;
+    keep(
+      gsap.to(viewport, {
+        scrollTop: target,
+        duration: 0.6,
+        ease: EASE.signature,
+        onComplete: () => {
+          tweening = false;
+          // Rows measured on the way may have moved it.
+          const settled = targetTop(at, align);
+          if (Math.abs(settled - viewport.scrollTop) > 1) viewport.scrollTop = settled;
+          update();
+          flash(at);
+        },
+      }),
+    );
+  };
+
+  // ── Choosing ─────────────────────────────────────────────────────────────
+  const placeCursor = (animate: boolean) => {
+    if (!selectable || active < 0 || active >= items.length) {
+      cursor.style.opacity = '0';
+      return;
+    }
+    const target = { y: sizes.offset(active), height: sizes.get(active) };
+    cursor.style.opacity = '';
+    if (animate && !reduced()) {
+      keep(gsap.to(cursor, { ...target, duration: 0.25, ease: EASE.swatch, overwrite: 'auto' }));
+      return;
+    }
+    // A glide on its way ends where it should.
+    if (gsap.isTweening(cursor)) return;
+    gsap.set(cursor, target);
+  };
+  const announce = () => {
+    const keys = [...selected];
+    const chosen = items.filter((item, i) => selected.has(keyOf(item, i)));
+    options.onSelect?.(keys, chosen);
+    root.dispatchEvent(new CustomEvent('mk:select', { bubbles: true, detail: { keys, items: chosen } }));
+  };
+  const choose = (index: number, mode: 'only' | 'toggle' | 'range') => {
+    if (!selectable || index < 0 || index >= items.length) return;
+    const key = keyOf(items[index]!, index);
+    const before = selected.has(key);
+    const previous = selected;
+    if (selectable === 'single' || mode === 'only') selected = new Set([key]);
+    else if (mode === 'toggle') {
+      selected = new Set(selected);
+      if (before) selected.delete(key);
+      else selected.add(key);
+    } else {
+      const from = anchor < 0 ? index : anchor;
+      selected = new Set(selected);
+      for (let i = Math.min(from, index); i <= Math.max(from, index); i++) selected.add(keyOf(items[i]!, i));
+    }
+    if (mode !== 'range') anchor = index;
+    paint();
+    const element = rows().find((row) => Number(row.dataset.index) === index);
+    // The check pops on the row that was just chosen.
+    if (element && selected.has(key) && !before) {
+      element.removeAttribute('data-mk-vl-just');
+      void element.offsetWidth;
+      element.setAttribute('data-mk-vl-just', '');
+      scope.timeout(() => element.removeAttribute('data-mk-vl-just'), 500);
+    }
+    status.textContent = `${textOf(items[index]!)} ${selected.has(key) ? 'seleccionado' : 'sin seleccionar'}`;
+    if (previous.size !== selected.size || [...selected].some((each) => !previous.has(each))) announce();
+  };
+  const setActive = (index: number, animate: boolean) => {
+    if (!items.length) return;
+    const at = Math.max(0, Math.min(items.length - 1, index));
+    const far = active < 0 || Math.abs(at - active) > 1;
+    active = at;
+    // The ring lives among the rows, so scrolling does not move it: it can glide first.
+    placeCursor(animate && !far);
+    // Keep it in view (no glide: the keyboard repeats fast).
+    const target = targetTop(at, 'auto');
+    if (Math.abs(target - viewport.scrollTop) > 0.5) viewport.scrollTop = target;
+    update();
+  };
+
+  scope.on(viewport, 'click', (event) => {
+    const mouse = event as MouseEvent;
+    const element = (mouse.target as Element | null)?.closest<HTMLElement>('[data-mk-vl-item]');
+    if (!element || !spacer.contains(element) || !selectable) return;
+    const index = Number(element.dataset.index);
+    active = index;
+    placeCursor(true);
+    if (selectable === 'multiple' && mouse.shiftKey) choose(index, 'range');
+    else choose(index, selectable === 'multiple' ? 'toggle' : 'only');
+    update();
+  });
+  scope.on(viewport, 'dblclick', (event) => {
+    const element = (event.target as Element | null)?.closest<HTMLElement>('[data-mk-vl-item]');
+    if (!element || !spacer.contains(element)) return;
+    const index = Number(element.dataset.index);
+    options.onActivate?.(items[index]!, index);
+  });
+
+  let typed = '';
+  let typedAt = 0;
+  scope.on(viewport, 'keydown', (event) => {
+    const key = event as KeyboardEvent;
+    if (!selectable || !items.length || key.altKey || key.ctrlKey || key.metaKey) return;
+    const page = Math.max(1, Math.floor(viewHeight() / estimate) - 1);
+    const from = active < 0 ? Math.min(items.length - 1, sizes.indexAt(viewport.scrollTop + 1)) : active;
+    let next: number | null = null;
+    switch (key.key) {
+      case 'ArrowDown':
+        next = active < 0 ? from : from + 1;
+        break;
+      case 'ArrowUp':
+        next = active < 0 ? from : from - 1;
+        break;
+      case 'PageDown':
+        next = from + page;
+        break;
+      case 'PageUp':
+        next = from - page;
+        break;
+      case 'Home':
+        next = 0;
+        break;
+      case 'End':
+        next = items.length - 1;
+        break;
+      case 'Enter':
+        if (active < 0) return;
+        key.preventDefault();
+        choose(active, selectable === 'multiple' ? 'toggle' : 'only');
+        options.onActivate?.(items[active]!, active);
+        return;
+      case ' ':
+        if (active < 0) return;
+        key.preventDefault();
+        choose(active, selectable === 'multiple' ? 'toggle' : 'only');
+        return;
+    }
+    if (next !== null) {
+      key.preventDefault();
+      setActive(next, true);
+      if (key.shiftKey && selectable === 'multiple') choose(active, 'range');
+      return;
+    }
+    // Typing jumps to the next row that starts with what was typed.
+    if (key.key.length === 1 && /\S/.test(key.key)) {
+      const now = Date.now();
+      typed = now - typedAt > 600 ? key.key.toLowerCase() : typed + key.key.toLowerCase();
+      typedAt = now;
+      const start = Math.max(0, active) + (typed.length === 1 ? 1 : 0);
+      for (let step = 0; step < items.length; step++) {
+        const index = (start + step) % items.length;
+        if (textOf(items[index]!).toLowerCase().startsWith(typed)) {
+          setActive(index, false);
+          break;
+        }
+      }
+    }
+  });
+
+  // ── More at the end ──────────────────────────────────────────────────────
+  let loadingMore = false;
+  let finished = false;
+  const append = (more: T[]) => {
+    if (!more.length) return;
+    const before = items.length;
+    items = [...items, ...more];
+    sizes = createSizes(heights());
+    update(true);
+    if (!reduced()) keep(blurIn(rows().filter((row) => Number(row.dataset.index) >= before), { from: 'rise', stagger: 0.03, duration: 0.4 }));
+  };
+  const reachEnd = () => {
+    if (!options.onEndReached || loadingMore || finished || range.end < items.length - Math.max(2, overscan)) return;
+    loadingMore = true;
+    foot.hidden = false;
+    foot.removeAttribute('data-mk-vl-end');
+    foot.setAttribute('aria-busy', 'true');
+    foot.textContent = 'Cargando…';
+    layoutSpacer();
+    Promise.resolve()
+      .then(() => options.onEndReached!())
+      .then((more) => {
+        if (scope.disposed) return;
+        loadingMore = false;
+        foot.removeAttribute('aria-busy');
+        // The app added them itself (setItems).
+        if (!more) {
+          foot.hidden = true;
+          layoutSpacer();
+          return;
+        }
+        if (!more.length) {
+          finished = true;
+          foot.setAttribute('data-mk-vl-end', '');
+          foot.textContent = items.length ? 'No hay más elementos' : '';
+          foot.hidden = !items.length;
+          status.textContent = 'No hay más elementos';
+          layoutSpacer();
+          return;
+        }
+        foot.hidden = true;
+        status.textContent = `${number.format(more.length)} más`;
+        append(more);
+      })
+      .catch(() => {
+        if (scope.disposed) return;
+        loadingMore = false;
+        finished = true;
+        foot.removeAttribute('aria-busy');
+        foot.textContent = 'No se pudo cargar';
+      });
+  };
+
+  update(true);
+
+  return {
+    setItems(next) {
+      if (scope.disposed) return;
+      const changed = next !== items;
+      items = [...next];
+      sizes = createSizes(heights());
+      if (active >= items.length) active = items.length - 1;
+      finished = false;
+      if (!loadingMore) foot.hidden = true;
+      refill = true;
+      update(true);
+      if (changed && !reduced()) keep(blurIn(rows().slice(0, 12), { from: 'soft', stagger: 0.015, duration: 0.3 }));
+    },
+    append(more) {
+      if (!scope.disposed) append(more);
+    },
+    scrollToIndex,
+    refresh() {
+      if (scope.disposed) return;
+      refill = true;
+      update(!external);
+    },
+    select(keys) {
+      selected = new Set(keys);
+      paint();
+    },
+    setRenderer(next) {
+      renderItem = next;
+      refill = true;
+      update(true);
+    },
+    get items() {
+      return [...items];
+    },
+    get range() {
+      return { ...range };
+    },
+    get selected() {
+      return [...selected];
+    },
+    container: spacer,
+    destroy: () => scope.dispose(),
+  };
+}