@develemit/web-hooks 0.3.1 → 0.5.0

package/dist/virtual-list.d.ts

@@ -0,0 +1,116 @@
+import { RefObject } from 'react';
+import { Virtualizer } from '@tanstack/react-virtual';
+import { a as Failure } from './log-helpers-rkbgYqZW.js';
+
+type ScrollAlign = 'start' | 'center' | 'end' | 'auto';
+declare const MAX_REALIGN_FRAMES = 3;
+/** A 0 height means "not laid out yet" (jsdom, or a read before first paint), so fall back to the estimate. */
+declare function measuredOrEstimate(measured: number | undefined, estimate: number): number;
+interface RealignInput {
+    align: ScrollAlign;
+    itemStart: number;
+    itemSize: number;
+    scrollOffset: number;
+    viewportSize: number;
+    frame: number;
+    maxFrames?: number;
+}
+declare function targetOffset(align: ScrollAlign, itemStart: number, itemSize: number, viewportSize: number): number;
+/** After rows above the target are measured the estimate can be off, so scroll again until the row sits where `align` says. */
+declare function shouldRealign({ align, itemStart, itemSize, scrollOffset, viewportSize, frame, maxFrames }: RealignInput): boolean;
+/** The first `initialCount` rows, used until the browser reports a viewport size. */
+declare function initialVisibleCount(count: number, initialCount: number): number;
+
+interface UseVirtualListOptions {
+    count: number;
+    estimateSize: (index: number) => number;
+    /** The overflow:auto element that scrolls. Omit with `windowScroll: true`. */
+    scrollRef?: RefObject<Element | null>;
+    /** Scroll with the page instead of an inner element. */
+    windowScroll?: boolean;
+    /** Distance from the top of the page to the list, for window scroll. */
+    scrollMargin?: number;
+    overscan?: number;
+    /** Measure each rendered row. Pass false when the app's own maths relies on `estimateSize`. */
+    measure?: boolean;
+    getItemKey?: (index: number) => string | number;
+    /** Rows rendered before the viewport size is known, so the server render isn't blank. */
+    initialCount?: number;
+}
+interface VirtualListItem {
+    index: number;
+    key: string | number | bigint;
+    start: number;
+    size: number;
+}
+interface ScrollToIndexOptions {
+    align?: ScrollAlign;
+}
+interface UseVirtualListResult {
+    items: VirtualListItem[];
+    totalSize: number;
+    /** Ref for each row element; the row also needs `data-index={item.index}`. */
+    measureRef: (el: Element | null) => void;
+    scrollToIndex: (index: number, options?: ScrollToIndexOptions) => void;
+    scrollToOffset: (offset: number) => void;
+    virtualizer: Virtualizer<Element, Element>;
+}
+declare function useVirtualList(options: UseVirtualListOptions): UseVirtualListResult;
+
+interface UseVirtualLogOptions {
+    /** Plain or raw lines; the last one may still be growing. */
+    lines: readonly string[];
+    scrollRef: RefObject<HTMLElement | null>;
+    /** Show only lines containing this text. Typing stays responsive on large logs. */
+    query?: string;
+    estimateSize?: (index: number) => number;
+    overscan?: number;
+    /** Snap back to the end whenever this changes (switching logs). */
+    resetKey?: unknown;
+    /** Filename used by `download`. */
+    filename?: string;
+}
+interface VirtualLogRow {
+    /** Position in the shown list. */
+    index: number;
+    /** Index into `lines`. */
+    lineIndex: number;
+    key: string | number | bigint;
+    start: number;
+    size: number;
+}
+interface UseVirtualLogResult {
+    rows: VirtualLogRow[];
+    totalSize: number;
+    measureRef: UseVirtualListResult['measureRef'];
+    isFiltering: boolean;
+    /** Lines shown: all of them, or the matches. */
+    shownCount: number;
+    atBottom: boolean;
+    unread: number;
+    jumpToBottom: () => void;
+    failures: readonly Failure[];
+    /** Which failure the last jump landed on, or -1. */
+    failurePosition: number;
+    jumpToFailure: (n: number) => boolean;
+    nextFailure: () => boolean;
+    previousFailure: () => boolean;
+    /** The whole log as text, whatever is rendered. */
+    text: (options?: {
+        stripAnsi?: boolean;
+    }) => string;
+    copyText: () => string;
+    download: (filename?: string) => void;
+    list: UseVirtualListResult;
+}
+declare function useVirtualLog({ lines, scrollRef, query, estimateSize, overscan, resetKey, filename, }: UseVirtualLogOptions): UseVirtualLogResult;
+
+interface LogToTextOptions {
+    /** Remove escape codes from each line. Default false: lines are joined as given. */
+    stripAnsi?: boolean;
+}
+declare function logToText(lines: readonly string[], options?: LogToTextOptions): string;
+/** Saves text as a file. The Blob URL is revoked right after the click. */
+declare function downloadText(filename: string, text: string): void;
+
+export { type LogToTextOptions, MAX_REALIGN_FRAMES, type RealignInput, type ScrollAlign, type ScrollToIndexOptions, type UseVirtualListOptions, type UseVirtualListResult, type UseVirtualLogOptions, type UseVirtualLogResult, type VirtualListItem, type VirtualLogRow, downloadText, initialVisibleCount, logToText, measuredOrEstimate, shouldRealign, targetOffset, useVirtualList, useVirtualLog };

package/dist/virtual-list.js

@@ -0,0 +1,287 @@
+"use client";
+import {
+  filterLines,
+  findFailures,
+  stripAnsi,
+  useFollowTail
+} from "./chunk-IVLRQ23V.js";
+
+// src/virtual-list/use-virtual-list.ts
+import { useCallback, useEffect, useRef } from "react";
+import {
+  observeWindowOffset,
+  observeWindowRect,
+  useVirtualizer,
+  windowScroll
+} from "@tanstack/react-virtual";
+
+// src/virtual-list/measure.ts
+var MAX_REALIGN_FRAMES = 3;
+function measuredOrEstimate(measured, estimate) {
+  return measured !== void 0 && measured > 0 ? measured : estimate;
+}
+function targetOffset(align, itemStart, itemSize, viewportSize) {
+  if (align === "end") return itemStart + itemSize - viewportSize;
+  if (align === "center") return itemStart + itemSize / 2 - viewportSize / 2;
+  return itemStart;
+}
+function shouldRealign({ align, itemStart, itemSize, scrollOffset, viewportSize, frame, maxFrames = MAX_REALIGN_FRAMES }) {
+  if (frame >= maxFrames) return false;
+  if (align === "auto") {
+    return itemStart < scrollOffset || itemStart + itemSize > scrollOffset + viewportSize;
+  }
+  const want = Math.max(0, targetOffset(align, itemStart, itemSize, viewportSize));
+  return Math.abs(scrollOffset - want) > 1;
+}
+function initialVisibleCount(count, initialCount) {
+  return Math.min(count, Math.max(0, initialCount));
+}
+
+// src/virtual-list/use-virtual-list.ts
+var ESTIMATED_ROW_FOR_SSR = 30;
+function useVirtualList(options) {
+  const {
+    count,
+    estimateSize,
+    scrollRef,
+    windowScroll: scrollsWindow = false,
+    scrollMargin = 0,
+    overscan = 10,
+    measure = true,
+    getItemKey,
+    initialCount = 30
+  } = options;
+  const frameRef = useRef(null);
+  const virtualizer = useVirtualizer({
+    count,
+    estimateSize,
+    overscan,
+    scrollMargin,
+    getScrollElement: () => scrollsWindow ? typeof window === "undefined" ? null : window : scrollRef?.current ?? null,
+    ...scrollsWindow ? {
+      observeElementRect: observeWindowRect,
+      observeElementOffset: observeWindowOffset,
+      scrollToFn: windowScroll,
+      initialOffset: () => typeof window === "undefined" ? 0 : window.scrollY
+    } : {},
+    // Seeds a viewport so the server render and first paint include rows.
+    initialRect: { width: 0, height: initialCount * ESTIMATED_ROW_FOR_SSR },
+    ...getItemKey ? { getItemKey } : {},
+    ...measure ? {
+      measureElement: (el, entry, instance) => {
+        const height = entry?.borderBoxSize?.[0]?.blockSize ?? el.getBoundingClientRect().height;
+        const index = Number(el.dataset.index);
+        const estimate = Number.isNaN(index) ? 0 : instance.options.estimateSize(index);
+        return measuredOrEstimate(height, estimate);
+      }
+    } : {}
+  });
+  const cancelRealign = useCallback(() => {
+    if (frameRef.current !== null && typeof cancelAnimationFrame === "function") cancelAnimationFrame(frameRef.current);
+    frameRef.current = null;
+  }, []);
+  useEffect(() => cancelRealign, [cancelRealign]);
+  const scrollToIndex = useCallback(
+    (index, { align = "auto" } = {}) => {
+      cancelRealign();
+      const last = Math.max(0, count - 1);
+      const target = Math.max(0, Math.min(index, last));
+      virtualizer.scrollToIndex(target, { align });
+      if (typeof requestAnimationFrame !== "function") return;
+      let frame = 0;
+      const check = () => {
+        frameRef.current = null;
+        const item = virtualizer.measurementsCache[target];
+        const offset = virtualizer.scrollOffset;
+        const viewport = virtualizer.scrollRect?.height;
+        if (!item || offset === null || !viewport) return;
+        const input = { align, itemStart: item.start - scrollMargin, itemSize: item.size, scrollOffset: offset - scrollMargin, viewportSize: viewport, frame };
+        if (!shouldRealign(input)) return;
+        frame += 1;
+        virtualizer.scrollToIndex(target, { align });
+        frameRef.current = requestAnimationFrame(check);
+      };
+      frameRef.current = requestAnimationFrame(check);
+    },
+    [virtualizer, count, scrollMargin, cancelRealign]
+  );
+  const scrollToOffset = useCallback((offset) => virtualizer.scrollToOffset(offset), [virtualizer]);
+  const rendered = virtualizer.getVirtualItems();
+  const items = rendered.map((v) => ({ index: v.index, key: v.key, start: v.start - scrollMargin, size: v.size }));
+  const fallback = items.length === 0 && count > 0 ? initialVisibleCount(count, initialCount) : 0;
+  if (fallback > 0) {
+    let start = 0;
+    for (let i = 0; i < fallback; i++) {
+      const size = estimateSize(i);
+      items.push({ index: i, key: getItemKey ? getItemKey(i) : i, start, size });
+      start += size;
+    }
+  }
+  return {
+    items,
+    totalSize: virtualizer.getTotalSize(),
+    measureRef: measure ? virtualizer.measureElement : noopRef,
+    scrollToIndex,
+    scrollToOffset,
+    virtualizer
+  };
+}
+function noopRef() {
+}
+
+// src/virtual-list/use-virtual-log.ts
+import { useCallback as useCallback2, useDeferredValue, useEffect as useEffect2, useMemo, useRef as useRef2, useState } from "react";
+
+// src/virtual-list/log-index.ts
+function emptyScan() {
+  return { lineCount: 0, firstLine: void 0, failures: [] };
+}
+function scanFailures(prev, lines) {
+  const appendOnly = prev.lineCount > 0 && lines.length >= prev.lineCount && lines[0] === prev.firstLine;
+  const from = appendOnly ? prev.lineCount - 1 : 0;
+  const kept = appendOnly ? prev.failures.filter((f) => f.index < from) : [];
+  const fresh = findFailures(lines.slice(from)).map((f) => ({ ...f, index: f.index + from }));
+  return { lineCount: lines.length, firstLine: lines[0], failures: [...kept, ...fresh] };
+}
+function visiblePosition(visible, lineIndex) {
+  if (!visible) return lineIndex;
+  let lo = 0;
+  let hi = visible.length - 1;
+  while (lo <= hi) {
+    const mid = lo + hi >> 1;
+    const value = visible[mid];
+    if (value === lineIndex) return mid;
+    if (value < lineIndex) lo = mid + 1;
+    else hi = mid - 1;
+  }
+  return -1;
+}
+function stepIndex(current, count, direction) {
+  if (count === 0) return -1;
+  if (current < 0) return direction === 1 ? 0 : count - 1;
+  return (current + direction + count) % count;
+}
+
+// src/virtual-list/log-text.ts
+function logToText(lines, options = {}) {
+  const rows = options.stripAnsi ? lines.map((line) => stripAnsi(line)) : lines;
+  return rows.join("\n");
+}
+function downloadText(filename, text) {
+  const url = URL.createObjectURL(new Blob([text], { type: "text/plain" }));
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
+// src/virtual-list/use-virtual-log.ts
+var DEFAULT_ROW = 18;
+function useVirtualLog({
+  lines,
+  scrollRef,
+  query = "",
+  estimateSize,
+  overscan = 12,
+  resetKey,
+  filename = "log.txt"
+}) {
+  const deferred = useDeferredValue(query);
+  const isFiltering = deferred.trim() !== "";
+  const visible = useMemo(() => isFiltering ? filterLines(lines, deferred) : null, [lines, deferred, isFiltering]);
+  const shownCount = visible ? visible.length : lines.length;
+  const scan = useRef2(emptyScan());
+  const failures = useMemo(() => {
+    scan.current = scanFailures(scan.current, lines);
+    return scan.current.failures;
+  }, [lines]);
+  const list = useVirtualList({
+    count: shownCount,
+    estimateSize: estimateSize ?? (() => DEFAULT_ROW),
+    scrollRef,
+    overscan
+  });
+  const lastIndex = shownCount - 1;
+  const follow = useFollowTail({
+    scrollRef,
+    itemCount: lines.length,
+    scrollToEnd: () => {
+      if (!isFiltering) list.scrollToIndex(lastIndex, { align: "end" });
+    },
+    resetKey
+  });
+  const baseline = useRef2(shownCount);
+  useEffect2(() => {
+    baseline.current = shownCount;
+  }, [deferred, resetKey]);
+  const unread = isFiltering ? Math.max(0, shownCount - baseline.current) : follow.unread;
+  useEffect2(() => {
+    if (isFiltering) list.scrollToOffset(0);
+  }, [deferred]);
+  const [failurePosition, setFailurePosition] = useState(-1);
+  const jumpToFailure = useCallback2(
+    (n) => {
+      const failure = failures[n];
+      if (!failure) return false;
+      const at = visiblePosition(visible, failure.index);
+      if (at < 0) return false;
+      setFailurePosition(n);
+      list.scrollToIndex(at, { align: "center" });
+      return true;
+    },
+    [failures, visible, list]
+  );
+  const step = useCallback2(
+    (direction) => {
+      for (let tries = 0, n = failurePosition; tries < failures.length; tries++) {
+        n = stepIndex(n, failures.length, direction);
+        if (jumpToFailure(n)) return true;
+      }
+      return false;
+    },
+    [failurePosition, failures.length, jumpToFailure]
+  );
+  const nextFailure = useCallback2(() => step(1), [step]);
+  const previousFailure = useCallback2(() => step(-1), [step]);
+  const text = useCallback2((options) => logToText(lines, options), [lines]);
+  const copyText = useCallback2(() => logToText(lines, { stripAnsi: true }), [lines]);
+  const download = useCallback2(
+    (name) => downloadText(name ?? filename, logToText(lines, { stripAnsi: true })),
+    [lines, filename]
+  );
+  const rows = list.items.map((item) => ({
+    ...item,
+    lineIndex: visible ? visible[item.index] ?? item.index : item.index
+  }));
+  return {
+    rows,
+    totalSize: list.totalSize,
+    measureRef: list.measureRef,
+    isFiltering,
+    shownCount,
+    atBottom: follow.atBottom,
+    unread,
+    jumpToBottom: follow.jumpToBottom,
+    failures,
+    failurePosition,
+    jumpToFailure,
+    nextFailure,
+    previousFailure,
+    text,
+    copyText,
+    download,
+    list
+  };
+}
+export {
+  MAX_REALIGN_FRAMES,
+  downloadText,
+  initialVisibleCount,
+  logToText,
+  measuredOrEstimate,
+  shouldRealign,
+  targetOffset,
+  useVirtualList,
+  useVirtualLog
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@develemit/web-hooks",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Shared React behavior hooks for develemit web apps: drawer swipe, focus trap, escape key and clipboard.",
   "license": "MIT",
   "author": "Emit Dutcher",
@@ -109,6 +109,16 @@
       "types": "./dist/push.d.ts",
       "import": "./dist/push.js",
       "require": "./dist/push.cjs"
+    },
+    "./terminal-output": {
+      "types": "./dist/terminal-output.d.ts",
+      "import": "./dist/terminal-output.js",
+      "require": "./dist/terminal-output.cjs"
+    },
+    "./virtual-list": {
+      "types": "./dist/virtual-list.d.ts",
+      "import": "./dist/virtual-list.js",
+      "require": "./dist/virtual-list.cjs"
     }
   },
   "main": "./dist/index.cjs",
@@ -123,11 +133,14 @@
     "access": "public"
   },
   "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "@tanstack/react-virtual": "^3.13.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",
+    "@tanstack/react-virtual": "^3.14.26",
     "@testing-library/react": "^16.0.0",
+    "@types/node": "^20.19.43",
     "@types/react": "^19.0.0",
     "@types/react-18": "npm:@types/react@^18.3.31",
     "@types/react-dom": "^19.0.0",
@@ -145,6 +158,11 @@
     "typescript-eslint": "^8.0.0",
     "vitest": "^3.0.0"
   },
+  "peerDependenciesMeta": {
+    "@tanstack/react-virtual": {
+      "optional": true
+    }
+  },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",