@danxbot/ui 20.19.0 → 20.20.0

package/dist/types/index.d.ts

@@ -116,7 +116,7 @@ export { Board, BoardColumn, BoardCard, BoardCardSurface, type BoardProps, type
 export { buildBoardModel, resolveMove, applyBoardMoves, useBoard, moveAnchor, columnLength, positionInColumn, type BoardModel, type MoveAnchor, type UseBoardResult, } from "./lib/board";
 export type { BoardAccessors, BoardColumnDef, BoardEdge, BoardColumnId, BoardColumnModel, BoardItemId, BoardMove, BoardMoveTarget, BoardMoveRequest, BoardMoveSource, BoardMoveVerdict, BoardReorderLabels, UseBoardOptions, } from "./lib/board";
 export { PagedWindowList, type PagedWindowItemPosition, type PagedWindowListProps, type PagedWindowStrings, } from "./components/PagedWindowList";
-export { PagedWindowStore, usePagedWindow, windowPageNumbers, type LoadCount, type LoadPage, type LoadPageContext, type PageResponse, type PageSnapshot, type PageStatus, type PagedWindow, type PagedWindowMode, type PagedWindowOptions, type PagedWindowSnapshot, type UsePagedWindowOptions, } from "./lib/paged-window";
+export { PAGED_WINDOW_SETTLE_MS, PagedWindowStore, usePagedWindow, windowPageNumbers, type LoadCount, type LoadPage, type LoadPageContext, type PageResponse, type PageSnapshot, type PageStatus, type PagedWindow, type PagedWindowMode, type PagedWindowOptions, type PagedWindowSnapshot, type UsePagedWindowOptions, } from "./lib/paged-window";
 export type { MessageRole, MessagePart, TextPart, CodePart, ReasoningPart, ToolPart, ToolStatus, FilePart, ComponentPart, ChatFile, ChatMessage, RenderContext, PartRenderer, PartRenderers, ChatComponentRenderer, ChatComponents, } from "./components/chat/types";
 export { Chat, ChatPopover, type ChatProps, type ChatPopoverProps, type ChatSurface, } from "./components/chat/Chat";
 export { Message, MessagePartView, ToolCall, type MessageProps, type MessageAction, type MessagePartViewProps, type ToolCallProps, } from "./components/chat/Message";

package/dist/types/lib/paged-window/index.d.ts

@@ -1,2 +1,2 @@
-export { PagedWindowStore, windowPageNumbers, type LoadCount, type LoadPage, type LoadPageContext, type PageResponse, type PageSnapshot, type PageStatus, type PagedWindowMode, type PagedWindowOptions, type PagedWindowSnapshot, } from "./store";
+export { PAGED_WINDOW_SETTLE_MS, PagedWindowStore, windowPageNumbers, type LoadCount, type LoadPage, type LoadPageContext, type PageResponse, type PageSnapshot, type PageStatus, type PagedWindowMode, type PagedWindowOptions, type PagedWindowSnapshot, } from "./store";
 export { usePagedWindow, type PagedWindow, type UsePagedWindowOptions } from "./use-paged-window";

package/dist/types/lib/paged-window/store.d.ts

@@ -12,6 +12,8 @@ export type LoadPage<T> = (page: number, context: LoadPageContext) => Promise<Pa
 /** Answers the list's length alone — no items. What a hidden (`count` mode) lane asks. */
 export type LoadCount = (context: LoadPageContext) => Promise<number>;
 export type PagedWindowMode = "pages" | "count";
+/** How long the viewer's page must stay put before the window moves to it, in ms. */
+export declare const PAGED_WINDOW_SETTLE_MS = 200;
 export type PageStatus = "loading" | "ready" | "error";
 export interface PageSnapshot<T> {
     page: number;
@@ -54,6 +56,12 @@ export interface PagedWindowOptions<T> {
     loadCount?: LoadCount;
     /** @default "pages" */
     mode?: PagedWindowMode;
+    /**
+     * How long the viewer's page must stay put before the window moves to it; 0
+     * moves it synchronously. A negative or fractional value throws.
+     * @default PAGED_WINDOW_SETTLE_MS
+     */
+    settleMs?: number;
 }
 /**
  * The pages to hold for an anchor: `windowPages` of them centred on it (the
@@ -64,13 +72,17 @@ export declare function windowPageNumbers(anchorPage: number, pageCount: number,
 export declare class PagedWindowStore<T> {
     private readonly pageSize;
     private readonly windowPages;
+    private readonly settleMs;
     private loadPage;
     private loadCount;
     private held;
     private total;
+    /** Where the viewer is; moves the instant they do. */
     private anchor;
-    /** The anchor the held pages were last synced to; differs from `anchor` only while frozen. */
+    /** The anchor the held pages were last synced to; differs from `anchor` while the viewer is still moving, or frozen. */
     private appliedAnchor;
+    /** Moves the window to `anchor` once it has been still for `settleMs`; null when no move is waiting. */
+    private settleTimer;
     private mode;
     private frozen;
     private epoch;
@@ -85,7 +97,7 @@ export declare class PagedWindowStore<T> {
     private countError;
     private snapshot;
     private listeners;
-    constructor({ pageSize, windowPages, loadPage, loadCount, mode }: PagedWindowOptions<T>);
+    constructor({ pageSize, windowPages, loadPage, loadCount, mode, settleMs, }: PagedWindowOptions<T>);
     /**
      * Replace the loaders. The React binding calls this after every commit so a
      * consumer's loaders can close over fresh state without the store being
@@ -95,7 +107,10 @@ export declare class PagedWindowStore<T> {
     setLoaders(loadPage: LoadPage<T>, loadCount: LoadCount | undefined): void;
     getSnapshot: () => PagedWindowSnapshot<T>;
     subscribe: (listener: () => void) => (() => void);
-    /** The viewer moved to another page. Ignored while frozen, applied on thaw. */
+    /**
+     * The viewer moved to another page. The window follows once they have stayed
+     * there for `settleMs`; while frozen it follows on thaw.
+     */
     setAnchorPage(page: number): void;
     /**
      * While true nothing about the window changes: it neither loads nor drops
@@ -130,7 +145,16 @@ export declare class PagedWindowStore<T> {
     private wanted;
     /** Bring the held pages to the wanted ones — unless frozen, when that waits for the thaw. */
     private sync;
-    /** `force` is `reset()`'s alone: it brings the window to its (new) list even while frozen. */
+    /** The viewer has settled on `anchor`: the window moves to it, in one step. */
+    private applyAnchor;
+    private clearSettle;
+    /**
+     * Moves the held pages to the window around `appliedAnchor` — which only
+     * `applyAnchor`, `thaw` and `reset` move, so a response arriving while the
+     * viewer is still moving brings in no page of the unsettled position.
+     * `force` is `reset()`'s alone: it brings the window to its (new) list even
+     * while frozen.
+     */
     private reconcile;
     /** Everything the frozen window put off, in the order the header promises. */
     private thaw;

package/dist/types/lib/paged-window/use-paged-window.d.ts

@@ -34,8 +34,14 @@ export interface PagedWindow<T> extends PagedWindowSnapshot<T> {
  * view which ones to show. `loadPage` answers one page AND the list's current
  * length, so the scrollbar can span `total` before most of it is loaded.
  *
+ * The window moves to the viewer's page only after it has stayed put for
+ * `settleMs` (200 ms by default), so a fast scroll loads the pages it lands
+ * on, never the ones it passes (DX-4614); a read for a page that leaves the
+ * window is aborted through its `signal`, and an aborted read is never an error.
+ *
  * `pageSize` and `windowPages` are fixed for the life of the hook: changing one
  * means every held page is cut differently, which is a different list — give it
- * a new `queryKey` and a new mount instead. It throws rather than guessing.
+ * a new `queryKey` and a new mount instead. `settleMs` is fixed too: the store
+ * reads it once. All three throw rather than guess.
  */
-export declare function usePagedWindow<T>({ pageSize, windowPages, loadPage, loadCount, queryKey, mode, }: UsePagedWindowOptions<T>): PagedWindow<T>;
+export declare function usePagedWindow<T>({ pageSize, windowPages, loadPage, loadCount, queryKey, mode, settleMs, }: UsePagedWindowOptions<T>): PagedWindow<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "20.19.0",
+  "version": "20.20.0",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",