@botiverse/raft-ui 0.51.0 → 0.52.0

package/dist/components/virtual-list/VirtualListContext.mjs

@@ -0,0 +1,5 @@
+import { createContext } from "react";
+//#region src/components/virtual-list/VirtualListContext.ts
+const VirtualListContext = createContext(null);
+//#endregion
+export { VirtualListContext };

package/dist/components/virtual-list/hooks/use-event-callback.mjs

@@ -0,0 +1,10 @@
+import { useCallback, useRef } from "react";
+//#region src/components/virtual-list/hooks/use-event-callback.ts
+/** A stable function that calls the `fn` of the latest render. */
+function useEventCallback(fn) {
+	const fnRef = useRef(fn);
+	fnRef.current = fn;
+	return useCallback((...args) => fnRef.current(...args), []);
+}
+//#endregion
+export { useEventCallback };

package/dist/components/virtual-list/hooks/use-ios-momentum-compensation.mjs

@@ -0,0 +1,148 @@
+import { useEventCallback } from "./use-event-callback.mjs";
+import { useLayoutEffect, useRef } from "react";
+//#region src/components/virtual-list/hooks/use-ios-momentum-compensation.ts
+/**
+* On iOS, writing `scrollTop` during momentum scrolling stops the fling. So while a touch scroll is
+* active, size changes above the view are accumulated and applied as `translateY(-compensation)` on
+* the items element; they are written to `scrollTop` (flushed) one second after the finger lifted, at
+* the top or bottom edge, or on the next touchstart.
+*/
+function useIosMomentumCompensation({ enabled, listElRef, itemsElRef, syncViewport, compensationYRef: iosCompYRef }) {
+	const touchSessionActiveRef = useRef(false);
+	const idleTimerRef = useRef(null);
+	const scrollSuppressTimerRef = useRef(null);
+	const forcedScrollTopRef = useRef(null);
+	const touchEndedRef = useRef(true);
+	const applyCompensationTransform = useEventCallback(() => {
+		const itemsEl = itemsElRef.current;
+		if (itemsEl) {
+			const compensation = iosCompYRef.current;
+			if (compensation === 0) itemsEl.style.transform = "";
+			else itemsEl.style.transform = `translateY(${-compensation}px)`;
+		}
+	});
+	const clearIdleTimer = useEventCallback(() => {
+		if (idleTimerRef.current !== null) {
+			clearTimeout(idleTimerRef.current);
+			idleTimerRef.current = null;
+		}
+	});
+	const startScrollSuppression = useEventCallback(() => {
+		if (scrollSuppressTimerRef.current !== null) clearTimeout(scrollSuppressTimerRef.current);
+		scrollSuppressTimerRef.current = setTimeout(() => {
+			scrollSuppressTimerRef.current = null;
+			forcedScrollTopRef.current = null;
+			syncViewport();
+		}, 200);
+	});
+	const flushCompensation = useEventCallback((reason) => {
+		clearIdleTimer();
+		const compensation = iosCompYRef.current;
+		iosCompYRef.current = 0;
+		touchSessionActiveRef.current = false;
+		applyCompensationTransform();
+		const listEl = listElRef.current;
+		if (listEl && compensation !== 0) {
+			const scrollTop = listEl.scrollTop + compensation;
+			listEl.scrollTop = scrollTop;
+			if (reason == "touchStart") {
+				forcedScrollTopRef.current = scrollTop;
+				startScrollSuppression();
+			}
+		}
+	});
+	const scheduleIdleFlush = useEventCallback(() => {
+		clearIdleTimer();
+		idleTimerRef.current = setTimeout(() => {
+			idleTimerRef.current = null;
+			if (touchEndedRef.current) flushCompensation("idleTimer");
+			else scheduleIdleFlush();
+		}, 1e3);
+	});
+	const handleTouchStart = useEventCallback(() => {
+		touchEndedRef.current = false;
+		if (touchSessionActiveRef.current) flushCompensation("touchStart");
+		touchSessionActiveRef.current = true;
+		scheduleIdleFlush();
+	});
+	const handleTouchEnd = useEventCallback(() => {
+		touchEndedRef.current = true;
+	});
+	const handleScrollDuringTouch = useEventCallback(() => {
+		if (touchSessionActiveRef.current) scheduleIdleFlush();
+	});
+	const clampCompensation = useEventCallback(() => {
+		const listEl = listElRef.current;
+		if (!listEl) return;
+		const maxScrollTop = listEl.scrollHeight - listEl.clientHeight;
+		iosCompYRef.current = Math.max(-listEl.scrollTop, Math.min(maxScrollTop - listEl.scrollTop, iosCompYRef.current));
+	});
+	const addCompensation = useEventCallback((deltaY) => {
+		if (!enabled || !touchSessionActiveRef.current) return false;
+		iosCompYRef.current += deltaY;
+		clampCompensation();
+		const listEl = listElRef.current;
+		if (listEl) {
+			if (listEl.scrollTop <= 0 && touchEndedRef.current) {
+				flushCompensation("scrollToTop");
+				return true;
+			}
+			if (iosCompYRef.current > 0) {
+				const maxScrollTop = listEl.scrollHeight - listEl.clientHeight;
+				if (listEl.scrollTop + iosCompYRef.current >= maxScrollTop) {
+					flushCompensation("overBottom");
+					return true;
+				}
+			}
+		}
+		applyCompensationTransform();
+		return true;
+	});
+	useLayoutEffect(() => {
+		if (!enabled) return;
+		const listEl = listElRef.current;
+		if (!listEl) return;
+		const itemsEl = itemsElRef.current;
+		listEl.addEventListener("touchstart", handleTouchStart, { passive: true });
+		listEl.addEventListener("touchend", handleTouchEnd, { passive: true });
+		listEl.addEventListener("touchcancel", handleTouchEnd, { passive: true });
+		listEl.addEventListener("scroll", handleScrollDuringTouch, { passive: true });
+		return () => {
+			listEl.removeEventListener("touchstart", handleTouchStart);
+			listEl.removeEventListener("touchend", handleTouchEnd);
+			listEl.removeEventListener("touchcancel", handleTouchEnd);
+			listEl.removeEventListener("scroll", handleScrollDuringTouch);
+			clearIdleTimer();
+			if (scrollSuppressTimerRef.current !== null) {
+				clearTimeout(scrollSuppressTimerRef.current);
+				scrollSuppressTimerRef.current = null;
+				forcedScrollTopRef.current = null;
+			}
+			if (iosCompYRef.current !== 0) {
+				if (itemsEl) itemsEl.style.transform = "";
+				listEl.scrollTop += iosCompYRef.current;
+				iosCompYRef.current = 0;
+			}
+			touchSessionActiveRef.current = false;
+		};
+	}, [
+		enabled,
+		listElRef,
+		itemsElRef,
+		handleTouchStart,
+		handleTouchEnd,
+		handleScrollDuringTouch,
+		clearIdleTimer,
+		iosCompYRef
+	]);
+	return {
+		addCompensation,
+		isScrollSuppressedWithForceRestore: useEventCallback((scrollTop) => {
+			const suppressed = scrollSuppressTimerRef.current !== null;
+			if (suppressed && listElRef.current && forcedScrollTopRef.current !== null && scrollTop === 0) listElRef.current.scrollTop = forcedScrollTopRef.current;
+			return suppressed;
+		})
+	};
+}
+//#endregion
+export { useIosMomentumCompensation };

package/dist/components/virtual-list/hooks/use-keyboard-scroll.mjs

@@ -0,0 +1,42 @@
+import { useCallback, useRef } from "react";
+//#region src/components/virtual-list/hooks/use-keyboard-scroll.ts
+/**
+* PageUp / PageDown / Space (Shift+Space up) scroll by the list's height minus `pageBottomOcclusion`
+* (what covers the bottom of the list, e.g. an input box) minus 32 px; Home / End and Cmd+Up / Cmd+Down
+* call `scrollTo({ position: "top" | "bottom" })`. Only keys pressed on the list itself (the scroll
+* container has focus) scroll it: a key pressed in a row (a button, a checkbox, a text field, a segmented
+* control) is left to that control, and so is a key a handler has already taken (`defaultPrevented`).
+*/
+function useKeyboardScroll(scrollTo, { pageBottomOcclusion = 0 } = {}) {
+	const occlusionRef = useRef(0);
+	occlusionRef.current = pageBottomOcclusion;
+	return { onKeyDown: useCallback((event) => {
+		if (event.defaultPrevented || event.target !== event.currentTarget) return;
+		if (event.key === "PageDown" || event.key === "PageUp" || event.key === " " || event.key === "Spacebar") {
+			const page = Math.max(event.currentTarget.clientHeight - occlusionRef.current - 32, 0);
+			if (page <= 0) return;
+			event.preventDefault();
+			event.currentTarget.scrollTop += event.key === "PageUp" || (event.key === " " || event.key === "Spacebar") && event.shiftKey ? -page : page;
+			return;
+		}
+		let position = null;
+		switch (event.key) {
+			case "Home":
+				position = "top";
+				break;
+			case "ArrowUp":
+				if (event.metaKey) position = "top";
+				break;
+			case "End":
+				position = "bottom";
+				break;
+			case "ArrowDown": if (event.metaKey) position = "bottom";
+		}
+		if (position) {
+			event.preventDefault();
+			scrollTo({ position });
+		}
+	}, [scrollTo]) };
+}
+//#endregion
+export { useKeyboardScroll };

package/dist/components/virtual-list/hooks/use-latest-ref.mjs

@@ -0,0 +1,10 @@
+import { useRef } from "react";
+//#region src/components/virtual-list/hooks/use-latest-ref.ts
+/** A ref whose `current` is the value of the latest render. */
+function useLatestRef(value) {
+	const ref = useRef(value);
+	ref.current = value;
+	return ref;
+}
+//#endregion
+export { useLatestRef };

package/dist/components/virtual-list/hooks/use-layout-effect-with-previous.mjs

@@ -0,0 +1,16 @@
+import { useLayoutEffect, useRef } from "react";
+//#region src/components/virtual-list/hooks/use-layout-effect-with-previous.ts
+/**
+* `useLayoutEffect(() => fn(previousDeps), deps)`: the layout-effect form of useMemoWithPrevious;
+* `fn` may return a cleanup.
+*/
+function useLayoutEffectWithPrevious(fn, deps) {
+	const previousRef = useRef(void 0);
+	useLayoutEffect(() => {
+		const cleanup = fn(previousRef.current);
+		previousRef.current = deps;
+		return cleanup;
+	}, deps);
+}
+//#endregion
+export { useLayoutEffectWithPrevious };

package/dist/components/virtual-list/hooks/use-memo-with-previous.mjs

@@ -0,0 +1,22 @@
+import { useLayoutEffect, useMemo, useRef } from "react";
+//#region src/components/virtual-list/hooks/use-memo-with-previous.ts
+/**
+* `useMemo(() => fn(previousDeps), deps)`: runs `fn` while rendering whenever `deps` change, with the
+* deps of the last committed render (`undefined` before the first commit).
+*
+* The previous deps are recorded at commit, not inside the memo: React may call a memo's function
+* more than once for one render (StrictMode does on purpose) or throw a render away, and either
+* would otherwise pass this render's own deps as `previous`.
+*/
+function useMemoWithPrevious(fn, deps) {
+	const previousRef = useRef(void 0);
+	const previous = previousRef.current;
+	useMemo(() => {
+		fn(previous);
+	}, deps);
+	useLayoutEffect(() => {
+		previousRef.current = deps;
+	});
+}
+//#endregion
+export { useMemoWithPrevious };

package/dist/components/virtual-list/hooks/use-non-passive-wheel.mjs

@@ -0,0 +1,23 @@
+import { useLayoutEffect } from "react";
+//#region src/components/virtual-list/hooks/use-non-passive-wheel.ts
+/**
+* Adds a non-passive `wheel` listener (so it may call `preventDefault`) to the element `getTarget`
+* returns, in a layout effect, only while `enabled` (a non-passive listener can hold up scrolling, so
+* none is added when it would not be used).
+*/
+function useNonPassiveWheel(getTarget, listener, enabled) {
+	useLayoutEffect(() => {
+		if (!enabled) return;
+		const target = getTarget();
+		if (target != null) target.addEventListener("wheel", listener, { passive: false });
+		return () => {
+			if (target != null) target.removeEventListener("wheel", listener);
+		};
+	}, [
+		getTarget,
+		listener,
+		enabled
+	]);
+}
+//#endregion
+export { useNonPassiveWheel };

package/dist/components/virtual-list/hooks/use-non-virtual-content-resize.mjs

@@ -0,0 +1,28 @@
+import { useEventCallback } from "./use-event-callback.mjs";
+import { getResizeObserverDelegate } from "../resize-observer/resize-observer-delegate.mjs";
+import { useLayoutEffect } from "react";
+//#region src/components/virtual-list/hooks/use-non-virtual-content-resize.ts
+/**
+* While `nonVirtual`, observes the items element and calls `onContentResize` when it resizes (with
+* virtualization on, the list calls it from its own measurements).
+*/
+function useNonVirtualContentResize(itemsElRef, onContentResize, nonVirtual) {
+	const notifyContentResize = useEventCallback(() => {
+		onContentResize?.();
+	});
+	useLayoutEffect(() => {
+		const itemsEl = itemsElRef.current;
+		if (itemsEl && nonVirtual) {
+			getResizeObserverDelegate().observe(itemsEl, notifyContentResize);
+			return () => {
+				getResizeObserverDelegate().unobserve(itemsEl);
+			};
+		}
+	}, [
+		itemsElRef,
+		notifyContentResize,
+		nonVirtual
+	]);
+}
+//#endregion
+export { useNonVirtualContentResize };

package/dist/components/virtual-list/hooks/use-scroll-anchor.mjs

@@ -0,0 +1,55 @@
+import { useCallback, useRef } from "react";
+//#region src/components/virtual-list/hooks/use-scroll-anchor.ts
+/**
+* Finds the first child of `container` whose box crosses the top of `scroller` (a binary search over
+* `getBoundingClientRect()`) and saves it with its top in `anchorRef`, or null when there is none.
+*/
+function snapshotAnchorElementStateAndSaveToRef(anchorRef, scroller, container) {
+	const children = Array.from(container.children);
+	const scrollerTop = scroller.getBoundingClientRect().top;
+	let lo = 0;
+	let hi = children.length - 1;
+	let found = -1;
+	let foundTop = 0;
+	while (lo <= hi) {
+		const mid = Math.floor((lo + hi) / 2);
+		const rect = children[mid].getBoundingClientRect();
+		if (rect.top <= scrollerTop && rect.bottom > scrollerTop) {
+			found = mid;
+			hi = mid - 1;
+			foundTop = rect.top;
+		} else lo = mid + 1;
+	}
+	if (found < 0) anchorRef.current = null;
+	else {
+		const element = children[found];
+		if (element) anchorRef.current = {
+			element,
+			top: foundTop
+		};
+		else anchorRef.current = null;
+	}
+}
+/**
+* `snapshotAnchorElementStateAndSaveToRef()` remembers the item at the top of the list;
+* `restoreScrollStateFromAnchor()` scrolls by how far it moved since; `clearAnchor()` forgets it.
+*/
+function useScrollAnchor(listElRef, getVisibleItemsEl) {
+	const anchorRef = useRef(null);
+	return {
+		snapshotAnchorElementStateAndSaveToRef: useCallback(() => {
+			const visibleItemsEl = getVisibleItemsEl();
+			if (listElRef.current && visibleItemsEl) snapshotAnchorElementStateAndSaveToRef(anchorRef, listElRef.current, visibleItemsEl);
+		}, [listElRef, getVisibleItemsEl]),
+		restoreScrollStateFromAnchor: useCallback(() => {
+			if (!anchorRef.current) return;
+			const moved = anchorRef.current.element.getBoundingClientRect().top - anchorRef.current.top;
+			listElRef.current?.scrollBy(0, moved);
+		}, [listElRef]),
+		clearAnchor: useCallback(() => {
+			anchorRef.current = null;
+		}, [])
+	};
+}
+//#endregion
+export { useScrollAnchor };

package/dist/components/virtual-list/index.d.mts

@@ -0,0 +1,5 @@
+import { ObservedResizeEntry } from "./resize-observer/resize-observer-delegate.mjs";
+import { MeasuredRef } from "./resize-observer/ResizeObserverWrapper.mjs";
+import { Column, FooterRender, ItemRenderProps, RenderAnomaly, RenderColInfo, RenderItemWithColsInfo, RenderReason, ScrollAlign, ScrollPosition, VirtualListApi, VirtualListProps, VirtualListScrollToOptions } from "./public-types.mjs";
+import { VirtualList } from "./VirtualList.mjs";
+export { VirtualList, type VirtualListApi, type Column as VirtualListColumn, type FooterRender as VirtualListFooterRender, type ItemRenderProps as VirtualListItemRenderProps, type MeasuredRef as VirtualListMeasuredRef, type VirtualListProps, type RenderAnomaly as VirtualListRenderAnomaly, type RenderColInfo as VirtualListRenderColInfo, type RenderItemWithColsInfo as VirtualListRenderItemWithColsInfo, type RenderReason as VirtualListRenderReason, type ObservedResizeEntry as VirtualListResizeEntry, type ScrollAlign as VirtualListScrollAlign, type ScrollPosition as VirtualListScrollPosition, type VirtualListScrollToOptions };