@danxbot/ui 20.9.0 → 20.11.0

package/dist/types/components/Board.d.ts

@@ -138,12 +138,19 @@ export interface BoardColumnProps<T> {
      * never colour or glyph alone (WCAG 1.4.1).
      */
     icon?: ReactNode;
+    /**
+     * DX-4540: controls drawn at the header's end, after the count — a
+     * `SortMenu`, say. A slot of content, not a boolean: supplying it is what
+     * adds it. It sits in the header, outside the scrolling list, so it stays
+     * put while the cards scroll.
+     */
+    actions?: ReactNode;
     /** The column's cards — a `BoardCard` per item, mapped by the consumer
-     *  exactly as `DragDropContainer`'s own children already are. This is the
-     *  virtualization seam — see the file header. */
+     *  exactly as `DragDropContainer`'s own children already are. A windowed
+     *  lane puts a `PagedWindowList` here — see the file header. */
     children?: ReactNode;
 }
-export declare function BoardColumn<T>({ column, emptyState, className, listClassName, accent, icon, children, }: BoardColumnProps<T>): import("react").JSX.Element;
+export declare function BoardColumn<T>({ column, emptyState, className, listClassName, accent, icon, actions, children, }: BoardColumnProps<T>): import("react").JSX.Element;
 export interface BoardCardProps {
     id: BoardItemId;
     /** Position within its OWN column right now — same contract as

package/dist/types/components/DragDrop.d.ts

@@ -37,10 +37,19 @@ export interface DragDropContainerProps {
      * @default "y"
      */
     axis?: DragAxis;
+    /**
+     * DX-4540: for a container that renders only a window of a longer list — the
+     * position in the whole list of its first item. Every announcement then
+     * speaks the real place ("position 221 of 500"), not the place among what
+     * happens to be rendered. Give both or neither.
+     */
+    offset?: number;
+    /** The whole list's length, counting the carried item when it lives here. See `offset`. */
+    total?: number;
     className?: string;
     children?: ReactNode;
 }
-export declare function DragDropContainer({ id, label, axis, className, children, }: DragDropContainerProps): import("react").JSX.Element;
+export declare function DragDropContainer({ id, label, axis, offset, total, className, children, }: DragDropContainerProps): import("react").JSX.Element;
 export interface DragDropItemProps {
     id: DragId;
     /**

package/dist/types/components/PagedWindowList.d.ts

@@ -0,0 +1,31 @@
+import { type ReactNode } from "react";
+import type { PagedWindow } from "../lib/paged-window";
+export interface PagedWindowStrings {
+    /** Shown in a page whose request failed. */
+    error: string;
+    /** The retry button's label. */
+    retry: string;
+}
+export interface PagedWindowItemPosition {
+    /** Position among the items currently shown, across every shown page. */
+    local: number;
+    /** Position in the whole list: `source.offset + local`. */
+    global: number;
+}
+export interface PagedWindowListProps<T> {
+    /** The window to render — what `usePagedWindow` returned. */
+    source: PagedWindow<T>;
+    /** Stable across renders and pages. Never an array index. */
+    getKey: (item: T) => string | number;
+    renderItem: (item: T, position: PagedWindowItemPosition) => ReactNode;
+    /**
+     * One item's height INCLUDING its spacing, in px, used for placeholders until
+     * real pages have been measured. Replaced by the measured mean as pages
+     * arrive, so it only has to be close.
+     */
+    estimatedItemHeight: number;
+    /** Words in the failed-page row. */
+    strings?: Partial<PagedWindowStrings>;
+    className?: string;
+}
+export declare function PagedWindowList<T>({ source, getKey, renderItem, estimatedItemHeight, strings, className, }: PagedWindowListProps<T>): import("react").JSX.Element;

package/dist/types/components/board/recipe.d.ts

@@ -21,6 +21,7 @@ export declare const board: import("tailwind-variants").TVReturnType<{
     header: string[];
     title: string;
     glyph: string;
+    trailing: string;
     label: string;
     list: string;
     empty: string;
@@ -50,6 +51,7 @@ export declare const board: import("tailwind-variants").TVReturnType<{
     header: string[];
     title: string;
     glyph: string;
+    trailing: string;
     label: string;
     list: string;
     empty: string;
@@ -79,6 +81,7 @@ export declare const board: import("tailwind-variants").TVReturnType<{
     header: string[];
     title: string;
     glyph: string;
+    trailing: string;
     label: string;
     list: string;
     empty: string;

package/dist/types/components/paged-window/PlaceholderBlock.d.ts

@@ -0,0 +1,21 @@
+import type { Ref } from "react";
+export interface PlaceholderBlockProps {
+    page: number;
+    /** `unheld` is a page outside the window: empty space of the right height. */
+    status: "unheld" | "loading" | "error";
+    /** The height of the page this stands for: items on it x the measured item height. */
+    height: number;
+    /** One item's height, for the loading rows. */
+    pitch: number;
+    /** Ref callback that returns its cleanup: how the list's observers find this block. */
+    blockRef: Ref<HTMLDivElement>;
+    errorText: string;
+    retryText: string;
+    onRetry: () => void;
+}
+/**
+ * The block of a page that has no cards to show: a page outside the window, one
+ * on its way, or one that failed. It holds the page's height either way, so the
+ * scrollbar does not move when the cards arrive.
+ */
+export declare function PlaceholderBlock({ page, status, height, pitch, blockRef, errorText, retryText, onRetry, }: PlaceholderBlockProps): import("react").JSX.Element;

package/dist/types/index.d.ts

@@ -111,10 +111,12 @@ export { tokenize, listLanguages, resolveLanguage, defineGrammar, registerGramma
 export { parseMarkdown, MarkdownNodes, sanitizeHref, type MdNode, type MdInline, type MdCodeRenderer, } from "./lib/syntax/markdown";
 export { DragDrop, DragDropContainer, DragDropItem, DragDropHandle, DragDropSurface, type DragDropProps, type DragDropContainerProps, type DragDropItemProps, type DragDropHandleProps, type DragDropSurfaceProps, } from "./components/DragDrop";
 export { KanbanBoard, type KanbanBoardProps, type KanbanLane, type KanbanMove, type KanbanRefusal, } from "./components/kanban/KanbanBoard";
-export { DEFAULT_DRAG_STRINGS, DRAG_INSTRUCTIONS_ID, DragInstructions, DragLiveRegion, DragSession, DragSessionProvider, applyMove, attachAutoScroll, attachKeyboardSensor, attachPointerSensor, attachSessionWindowListeners, isNoOp, resolveTarget, sameTarget, scrollVelocity, useCreateDragSession, useDragAnnouncements, useDragSession, useDragState, useDraggable, useDropContainer, type ContainerId, type DragAxis, type DragCancelEvent, type DragEndEvent, type DragId, type DragMode, type DragPhase, type DragSessionCallbacks, type DragStartEvent, type DragState, type AutoScrollOptions, type DragAnnouncementContext, type DragAnnouncementOptions, type DragAnnouncements, type DragInstructionsProps, type DragLiveRegionProps, type DragStrings, type DropTarget, type KeyboardSensorOptions, type PointerActivation, } from "./lib/dnd";
+export { DEFAULT_DRAG_STRINGS, DRAG_INSTRUCTIONS_ID, DragInstructions, DragLiveRegion, DragSession, DragSessionProvider, applyMove, attachAutoScroll, attachKeyboardSensor, attachPointerSensor, attachSessionWindowListeners, isNoOp, resolveTarget, sameTarget, scrollVelocity, useCreateDragSession, useDragAnnouncements, useDragSession, useDragState, useDragLive, useDraggable, useDropContainer, type ContainerId, type DragAxis, type DragCancelEvent, type DragEndEvent, type DragId, type DragMode, type DragPhase, type DragSessionCallbacks, type DragStartEvent, type DragState, type AutoScrollOptions, type DragAnnouncementContext, type DragAnnouncementOptions, type DragAnnouncements, type DragInstructionsProps, type DragLiveRegionProps, type DragStrings, type DropTarget, type KeyboardSensorOptions, type PointerActivation, } from "./lib/dnd";
 export { Board, BoardColumn, BoardCard, BoardCardSurface, type BoardProps, type BoardColumnProps, type BoardCardProps, type BoardCardSurfaceProps, } from "./components/Board";
-export { buildBoardModel, resolveMove, applyBoardMoves, useBoard, type BoardModel, type UseBoardResult, } from "./lib/board";
-export type { BoardAccessors, BoardColumnDef, BoardColumnId, BoardColumnModel, BoardItemId, BoardMove, BoardMoveRequest, BoardMoveSource, BoardMoveVerdict, UseBoardOptions, } from "./lib/board";
+export { buildBoardModel, resolveMove, applyBoardMoves, useBoard, moveAnchor, type BoardModel, type MoveAnchor, type UseBoardResult, } from "./lib/board";
+export type { BoardAccessors, BoardColumnDef, BoardEdge, BoardColumnId, BoardColumnModel, BoardItemId, BoardMove, BoardMoveRequest, BoardMoveSource, BoardMoveVerdict, UseBoardOptions, } from "./lib/board";
+export { PagedWindowList, type PagedWindowItemPosition, type PagedWindowListProps, type PagedWindowStrings, } from "./components/PagedWindowList";
+export { PagedWindowStore, usePagedWindow, windowPageNumbers, type LoadPage, type LoadPageContext, type PageResponse, type PageSnapshot, type PageStatus, type PagedWindow, 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/board/anchor.d.ts

@@ -0,0 +1,37 @@
+/**
+ * ==== MOVE ANCHOR ====
+ *
+ * What a server needs to place a card the board moved, when the board holds
+ * only a window of the column (DX-4540). A drop knows exactly one thing about
+ * where it landed: which LOADED neighbours it is between. It never knows the
+ * card's position in the whole column, and a client that tries to compute one
+ * from `to.index` is wrong the moment the window does not start at the top.
+ * So the request names the neighbours, and the server finds the place.
+ *
+ * `to.index` counts the destination's LOADED cards with the moved card already
+ * removed (the board's one index rule), so the card lands before
+ * `rest[to.index]` and after `rest[to.index - 1]`, where `rest` is the
+ * destination's loaded cards without the moved one. Either neighbour may be
+ * absent: at the start of the loaded run there is nothing loaded above, at the
+ * end nothing below, and an empty destination has neither. A server that is
+ * given `beforeId` places the card directly above it; given only `afterId`,
+ * directly below it; given neither, the destination was empty.
+ *
+ * AN EDGE INTENT TRUMPS THE NEIGHBOURS. "Move to top" in a window that starts
+ * at card 221 means the top of the column, which no loaded neighbour can say,
+ * so the anchor carries the edge and no ids.
+ */
+import type { BoardEdge, BoardItemId, BoardMove } from "./types";
+export interface MoveAnchor {
+    /** The loaded card the moved card lands directly above. */
+    beforeId?: BoardItemId;
+    /** The loaded card the moved card lands directly below. */
+    afterId?: BoardItemId;
+    /** The moved card goes to the very top or bottom of the whole column; no ids are given. */
+    edge?: BoardEdge;
+}
+/**
+ * @param destinationItems the destination column's LOADED cards (the moved card
+ *   may be among them, for a same-column move).
+ */
+export declare function moveAnchor<T>(destinationItems: readonly T[], move: BoardMove, getId: (item: T) => BoardItemId): MoveAnchor;

package/dist/types/lib/board/index.d.ts

@@ -8,7 +8,8 @@
  * NOT wired into the package's top-level `src/index.ts` — that barrel is
  * owned by the contract's author, not this agent (see this round's brief).
  */
-export type { BoardAccessors, BoardColumnDef, BoardColumnId, BoardColumnModel, BoardItemId, BoardMove, BoardMoveRequest, BoardMoveSource, BoardMoveVerdict, UseBoardOptions, } from "./types";
+export type { BoardAccessors, BoardColumnDef, BoardEdge, BoardColumnId, BoardColumnModel, BoardItemId, BoardMove, BoardMoveRequest, BoardMoveSource, BoardMoveVerdict, UseBoardOptions, } from "./types";
 export { buildBoardModel, type BoardModel } from "./model";
+export { moveAnchor, type MoveAnchor } from "./anchor";
 export { applyBoardMoves, resolveMove, type ResolveMoveContext, type ResolvedMove, } from "./move";
 export { useBoard, type UseBoardResult } from "./use-board";

package/dist/types/lib/board/types.d.ts

@@ -74,11 +74,42 @@ export interface BoardColumnDef {
      * Soft cap on item count. Exceeding it is a VISUAL event, not a blocked move
      * — a WIP limit exists to interrupt a human, and a board that refuses the
      * drop instead just teaches people to work around the board. The core reports
-     * `overWip`; the view layer is responsible for making it loud.
+     * `overWip`; the view layer is responsible for making it loud. The limit is
+     * judged against the column's real length (`total`), not what is loaded.
      */
     wipLimit?: number;
+    /**
+     * DX-4540: the column's real length when `items` holds only the cards loaded so
+     * far (a windowed lane). The model's `count` is this number, and `overWip`,
+     * the move menu's "is there anything above/below" and the drag announcements
+     * all read it. `null` means the length is still being read: the column is
+     * neither empty nor over its limit, and `count` falls back to the loaded
+     * cards. Omitted, every card of the column is loaded and the count is theirs.
+     */
+    total?: number | null;
+    /**
+     * DX-4540: the position in the whole column of the first loaded card, so a
+     * card at index 0 of `items` is spoken as "position 221", not "position 1".
+     * Only meaningful with `total`; the loaded cards must be one contiguous run
+     * of the column. @default 0
+     */
+    offset?: number;
 }
-/** One item's move. `to.index` counts the destination list without this item. */
+/**
+ * Where a move lands beyond what is loaded. In a windowed column `to.index` can
+ * only name a position among the LOADED cards, so a move to "the very top" or
+ * "the very bottom" of the column says so here and the consumer sends that
+ * intent to its server (see `moveAnchor`). In a column with every card loaded
+ * the edge is the same place as `index` 0 / the end, so a consumer that ignores
+ * it is still right.
+ */
+export type BoardEdge = "top" | "bottom";
+/**
+ * One item's move. `to.index` counts the destination list without this item —
+ * the LOADED list, in a windowed column. `to.edge`, when present, is the
+ * intent the index cannot carry; the index is then the nearest loaded position
+ * (0 for `"top"`, one past the last loaded card for `"bottom"`).
+ */
 export interface BoardMove {
     itemId: BoardItemId;
     from: {
@@ -88,6 +119,7 @@ export interface BoardMove {
     to: {
         columnId: BoardColumnId;
         index: number;
+        edge?: BoardEdge;
     };
 }
 /**
@@ -125,11 +157,22 @@ export type BoardMoveVerdict = {
 export interface BoardColumnModel<T> {
     id: BoardColumnId;
     label: string;
+    /** The cards loaded. All of the column's cards unless the column is windowed. */
     items: readonly T[];
-    /** Count is on the model because the view needs it before it renders rows. */
+    /**
+     * The column's length: its `total` when the definition gave one, else the
+     * loaded cards. Count is on the model because the view needs it before it
+     * renders rows — and because it is computed ONCE here: the badge, the empty
+     * state, the WIP verdict, the move menu and the announcements all read this
+     * number, never their own.
+     */
     count: number;
+    /** `true` while a windowed column's length is still being read (`total: null`). `count` is then the loaded cards. */
+    counting: boolean;
+    /** Position in the whole column of `items[0]`; 0 unless the column is windowed. */
+    offset: number;
     wipLimit: number | undefined;
-    /** `true` when `count` exceeds `wipLimit`. Always false with no limit set. */
+    /** `true` when `count` exceeds `wipLimit`. Always false with no limit set, and while `counting`. */
     overWip: boolean;
 }
 export interface UseBoardOptions<T> {

package/dist/types/lib/dnd/announce.d.ts

@@ -7,7 +7,7 @@ export interface DragAnnouncementContext {
     label: string;
     container: ContainerId;
     containerLabel: string;
-    /** 1-based, as spoken. */
+    /** 1-based, as spoken, in the WHOLE container — a windowed container reports its real offset and length (DX-4540). */
     position: number;
     /**
      * The list length WITH the carried item counted in it, so `position` is never

package/dist/types/lib/dnd/index.d.ts

@@ -12,5 +12,5 @@ export { DragSession, type StartArgs } from "./session";
 export { attachPointerSensor, attachSessionWindowListeners, type PointerActivation, type PointerSensorOptions, } from "./sensors/pointer";
 export { attachKeyboardSensor, type KeyboardSensorOptions, } from "./sensors/keyboard";
 export { attachAutoScroll, scrollVelocity, type AutoScrollOptions, } from "./autoscroll";
-export { DragSessionProvider, useCreateDragSession, useDragSession, useDragState, useDraggable, useDropContainer, type UseDraggableOptions, type UseDraggableResult, type UseDropContainerOptions, type UseDropContainerResult, } from "./use-drag";
+export { DragSessionProvider, useCreateDragSession, useDragSession, useDragState, useDragLive, useDraggable, useDropContainer, type UseDraggableOptions, type UseDraggableResult, type UseDropContainerOptions, type UseDropContainerResult, } from "./use-drag";
 export { DEFAULT_DRAG_STRINGS, DRAG_INSTRUCTIONS_ID, DragInstructions, DragLiveRegion, useDragAnnouncements, type DragAnnouncementContext, type DragAnnouncementOptions, type DragAnnouncements, type DragInstructionsProps, type DragLiveRegionProps, type DragStrings, } from "./announce";

package/dist/types/lib/dnd/session.d.ts

@@ -94,6 +94,18 @@ export declare class DragSession {
     cancel(): void;
     /** The container the pointer is over right now, or null. */
     containerAtPoint(point: Point): string | null;
+    /**
+     * Where a drop target sits, as a person is told it: 1-based, in the WHOLE
+     * container, with the whole container's length counted with the carried item
+     * in it. A container that renders every item is its own whole (the items
+     * registered under it); a windowed one says so at registration (`offset`,
+     * `total`) and the answer follows. `index` counts the container with the
+     * carried item already removed — the engine's one index rule.
+     */
+    spokenPosition(container: string, index: number, carried: DragId): {
+        position: number;
+        total: number;
+    };
     /** How many items a container holds once the carried one is taken out. */
     slotCount(container: string): number;
 }

package/dist/types/lib/dnd/types.d.ts

@@ -95,6 +95,15 @@ export interface ContainerRegistration {
     id: ContainerId;
     element: HTMLElement;
     axis: DragAxis;
+    /**
+     * DX-4540: for a container that renders only a window of a longer list. The
+     * position in the whole list of its first registered item, so a drop spoken
+     * as "position 221 of 500" is true. Absent for a container that holds every
+     * item.
+     */
+    offset?: number;
+    /** The whole list's length, the carried item counted in it when it lives here. See `offset`. */
+    total?: number;
 }
 /** One item's measured box, taken at snapshot time. */
 export interface ItemRect {

package/dist/types/lib/dnd/use-drag.d.ts

@@ -14,6 +14,16 @@ export declare function useDragSession(component: string): DragSession;
 export declare function useCreateDragSession(callbacks: DragSessionCallbacks): DragSession;
 /** Subscribe to the session. */
 export declare function useDragState(session: DragSession): DragState;
+/**
+ * True while a card is being carried in the enclosing `<DragDrop>`, and false
+ * outside one — it never throws, because the callers that ask (a windowed list
+ * deciding whether it may drop a page) are ordinary components that are
+ * sometimes inside a board and sometimes not.
+ *
+ * Reads only `phase === "dragging"`, so it re-renders its caller when a drag
+ * starts or ends and not on every pointer move, which `useDragState` would.
+ */
+export declare function useDragLive(): boolean;
 export interface UseDraggableOptions {
     id: DragId;
     container: ContainerId;
@@ -45,6 +55,10 @@ export declare function useDraggable(session: DragSession, options: UseDraggable
 export interface UseDropContainerOptions {
     id: ContainerId;
     axis?: DragAxis;
+    /** See `ContainerRegistration.offset` — a windowed container's first item's place in the whole list. */
+    offset?: number;
+    /** See `ContainerRegistration.total` — a windowed container's whole length. */
+    total?: number;
 }
 export interface UseDropContainerResult {
     setContainerRef: (el: HTMLElement | null) => void;

package/dist/types/lib/dom/scroll-ancestor.d.ts

@@ -0,0 +1,15 @@
+export type ScrollAxis = "x" | "y";
+export interface ScrollBoxOptions {
+    /** The axes that count; a box scrolling along any of them qualifies. @default ["y"] */
+    axes?: readonly ScrollAxis[];
+    /** Also require the content to overflow the box on that axis, not merely allow scrolling. @default false */
+    mustOverflow?: boolean;
+}
+export interface ScrollAncestorOptions extends ScrollBoxOptions {
+    /** Whether `from` itself may be the answer. Required: it is a statement about the caller. */
+    includeSelf: boolean;
+}
+/** Does `el` scroll along any of the given axes? */
+export declare function isScrollBox(el: HTMLElement, { axes, mustOverflow }?: ScrollBoxOptions): boolean;
+/** The nearest box that scrolls, walking up from `from`; null when none does. */
+export declare function nearestScrollAncestor(from: Element | null, { includeSelf, ...box }: ScrollAncestorOptions): HTMLElement | null;

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

@@ -0,0 +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 { usePagedWindow, type PagedWindow, type UsePagedWindowOptions } from "./use-paged-window";

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

@@ -0,0 +1,139 @@
+export interface PageResponse<T> {
+    /** This page's items, in order. Fewer than `pageSize` only for the last page. */
+    items: readonly T[];
+    /** The WHOLE list's length right now. Every response refreshes it. */
+    total: number;
+}
+export interface LoadPageContext {
+    /** Aborted when the page is dropped, re-requested or the window is reset. */
+    signal: AbortSignal;
+}
+export type LoadPage<T> = (page: number, context: LoadPageContext) => Promise<PageResponse<T>>;
+/** 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";
+export type PageStatus = "loading" | "ready" | "error";
+export interface PageSnapshot<T> {
+    page: number;
+    status: PageStatus;
+    /** Empty unless `ready`. A page being re-read keeps its old items and stays `ready`. */
+    items: readonly T[];
+    /** True while a `ready` page is being re-read in place. */
+    refreshing: boolean;
+    /** What the load rejected with. Only on `error`. */
+    error: unknown;
+    /** Part of the loaded run — its items are in `items`. A ready page past a hole is not, until the hole closes. */
+    shown: boolean;
+}
+export interface PagedWindowSnapshot<T> {
+    mode: PagedWindowMode;
+    /** The list's length as the latest response reported it; null before the first. */
+    total: number | null;
+    pageSize: number;
+    /** 0 until `total` is known, then `ceil(total / pageSize)`. */
+    pageCount: number;
+    /** The page the viewer is looking at. */
+    anchorPage: number;
+    /** Counts resets, so a view can scroll back to the top when the query changed. */
+    epoch: number;
+    /** The held pages, ascending. At most `windowPages` of them. */
+    pages: readonly PageSnapshot<T>[];
+    /** The loaded run: the items of the shown pages, in list order. At most `windowPages * pageSize`. */
+    items: readonly T[];
+    /** The position in the whole list of `items[0]`; 0 when nothing is loaded. */
+    offset: number;
+    /** What the last `loadCount` rejected with; undefined otherwise. */
+    countError: unknown;
+}
+export interface PagedWindowOptions<T> {
+    pageSize: number;
+    /** How many pages are held at once. @default 3 */
+    windowPages?: number;
+    loadPage: LoadPage<T>;
+    /** Required to use `count` mode. */
+    loadCount?: LoadCount;
+    /** @default "pages" */
+    mode?: PagedWindowMode;
+}
+/**
+ * The pages to hold for an anchor: `windowPages` of them centred on it (the
+ * extra page of an even window goes after), clipped to `[0, pageCount)`. Pure,
+ * so the rule is testable without a store.
+ */
+export declare function windowPageNumbers(anchorPage: number, pageCount: number, windowPages: number): number[];
+export declare class PagedWindowStore<T> {
+    private readonly pageSize;
+    private readonly windowPages;
+    private loadPage;
+    private loadCount;
+    private held;
+    private total;
+    private anchor;
+    /** The anchor the held pages were last synced to; differs from `anchor` only while frozen. */
+    private appliedAnchor;
+    private mode;
+    private frozen;
+    private epoch;
+    private nextToken;
+    private countRequest;
+    private countError;
+    private snapshot;
+    private listeners;
+    constructor({ pageSize, windowPages, loadPage, loadCount, mode }: 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
+     * rebuilt (rebuilding drops every held page). A change in WHAT is loaded is a
+     * `reset`, never this.
+     */
+    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. */
+    setAnchorPage(page: number): void;
+    /**
+     * While true the window neither loads nor drops pages, whatever the anchor or
+     * the total does. A drag needs it: the carried card is mounted in its page,
+     * and dropping that page mid-drag would unmount the card and cancel the drag.
+     */
+    setFrozen(frozen: boolean): void;
+    /** `count` holds and requests no cards, only the length (see the file header). */
+    setMode(mode: PagedWindowMode): void;
+    /** The query changed: forget everything, return to the first page. */
+    reset(): void;
+    /** Re-read one held page in place. A page that is not held loads fresh when it is next wanted. */
+    invalidatePage(page: number): void;
+    /** Re-read every held page in place; in `count` mode, re-ask the length. */
+    invalidateAll(): void;
+    /** Load the first window (or the length). The binding calls it on mount, and again after a `stop`. */
+    start(): void;
+    /** Abort every request and release every page. The binding calls it on unmount. */
+    stop(): void;
+    private requireCountLoader;
+    private pageCount;
+    /**
+     * Pages to hold now. None in `count` mode. Page 0 alone before the first
+     * response (the count is unknown) and for an empty list: an empty page is
+     * still held, because it is what `invalidateAll` re-reads when the list gets
+     * its first item — an empty lane that holds nothing could never find out it
+     * was no longer empty.
+     */
+    private wanted;
+    /** Bring the held pages to the wanted ones — unless frozen, when that waits for the thaw. */
+    private sync;
+    /** Start (or restart) a page's request; whatever was in flight is abandoned. */
+    private request;
+    private settle;
+    private requestCount;
+    private settleCount;
+    private abortCount;
+    private dropAll;
+    /**
+     * The longest unbroken stretch of ready pages inside the list, lowest on a
+     * tie. Pages past the list's end (it shrank while the window was frozen) are
+     * not part of any run.
+     */
+    private loadedRun;
+    private build;
+    private publish;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * How tall one item really is — measured, not guessed. DX-4540.
+ *
+ * A page that is not held is drawn as a placeholder of `items x pitch`, so the
+ * scrollbar is only as true as the pitch. `estimated` stands in until pages
+ * have been seen; after that the pitch is the MEAN over every item measured,
+ * which is a ResizeObserver over the page blocks.
+ *
+ * EVERY block is observed, because a block turns from placeholder to cards (and
+ * back) without its element being replaced: only a block that currently holds
+ * cards (`data-count`) is a measurement of what a card costs; a placeholder's
+ * own size is the estimate drawn back at us. A block that stops holding cards,
+ * or is removed, leaves its LAST reading in the mean (`departed`), so dropping
+ * a page does not make the estimate lurch and every placeholder above the
+ * viewer resize with it.
+ *
+ * A change under half a pixel is not published: re-laying-out every placeholder
+ * in a long list for sub-pixel drift is cost with no picture.
+ */
+export declare function useMeasuredPitch(estimated: number): {
+    pitch: number;
+    observe: (el: HTMLElement) => () => void;
+};

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

@@ -0,0 +1,20 @@
+import type { ScrollRoot } from "./use-scroll-root";
+/**
+ * The page the window should centre on: the middle one (lower middle when
+ * even) of the pages whose blocks intersect the root. A viewport shorter than
+ * a page sees one or two; the window of three covers either. Null when nothing
+ * is in view (a hidden scroller), so the window keeps where it was.
+ */
+export declare function centrePage(visible: ReadonlySet<Element>): number | null;
+/**
+ * Which pages are in view, from one IntersectionObserver over every page block,
+ * rooted at the scroller — no scroll listener, no polling. DX-4540.
+ *
+ * `observe(el)` is what a block's ref calls; it returns the cleanup. It is
+ * stable, and blocks that mount before the observer exists (it needs the
+ * resolved scroller) are picked up when it does. Whenever the set in view
+ * changes, `onCentre` is told the page to centre on.
+ */
+export declare function usePageVisibility(scroller: ScrollRoot | null, onCentre: (page: number) => void): {
+    observe: (el: HTMLElement) => () => void;
+};

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

@@ -0,0 +1,41 @@
+import { type PagedWindowMode, type PagedWindowOptions, type PagedWindowSnapshot } from "./store";
+export interface UsePagedWindowOptions<T> extends PagedWindowOptions<T> {
+    /**
+     * Names WHAT is being listed: the filter, the sort, the time range. When it
+     * changes the window forgets every page, returns to the first and the list
+     * scrolls back to the top. A change in a loader's identity alone does not:
+     * a loader closing over fresh state must not throw away what is held.
+     */
+    queryKey: string;
+    /**
+     * `"count"` loads no cards, only the list's length (through `loadCount`), and
+     * keeps it live: a hidden lane that still needs a true badge. Back to
+     * `"pages"`, the window loads again.
+     * @default "pages"
+     */
+    mode?: PagedWindowMode;
+}
+export interface PagedWindow<T> extends PagedWindowSnapshot<T> {
+    /** The viewer moved to this page. `PagedWindowList` reports it; a custom view may too. */
+    setAnchorPage: (page: number) => void;
+    /** Re-read one held page in place — a card on it changed. */
+    invalidatePage: (page: number) => void;
+    /** Re-read every held page in place — a card was created, moved or removed. In `count` mode, re-ask the length. */
+    invalidateAll: () => void;
+    /**
+     * While true the window neither loads nor drops pages. `PagedWindowList`
+     * sets it for the length of a drag: the carried card is mounted in its page,
+     * and dropping that page mid-drag would unmount the card and cancel the drag.
+     */
+    setFrozen: (frozen: boolean) => void;
+}
+/**
+ * Holds `windowPages` (default 3) pages of a long server-side list and tells a
+ * 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.
+ *
+ * `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.
+ */
+export declare function usePagedWindow<T>({ pageSize, windowPages, loadPage, loadCount, queryKey, mode, }: UsePagedWindowOptions<T>): PagedWindow<T>;

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

@@ -0,0 +1,18 @@
+/** The element a list scrolls in: `el` is null when the page itself scrolls (the viewport). */
+export interface ScrollRoot {
+    el: HTMLElement | null;
+}
+/**
+ * Finds the box a list scrolls in, once the list is in the DOM. DX-4540.
+ *
+ * Returns a ref callback for the list's root and the root it resolved (null
+ * until mounted). The list's OWN element counts: a list whose class sets
+ * `overflow-y-auto` is its own scroller, and one dropped into a board lane
+ * finds the lane's container above it. Resolved on mount only — a list does
+ * not change scroller during its life, and re-walking on every render would
+ * make the IntersectionObserver rooted at it be torn down and rebuilt.
+ */
+export declare function useScrollRoot(): {
+    ref: (el: HTMLElement | null) => void;
+    scroller: ScrollRoot | null;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "20.9.0",
+  "version": "20.11.0",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",
@@ -74,7 +74,7 @@
     "gates": "npm run shoot && npm run a11y && node scripts/shoot-overlays.mjs && npm run probe",
     "a11y": "node scripts/a11y-scan.mjs",
     "shoot": "node scripts/shoot.mjs",
-    "probe": "node scripts/probe-scale.mjs && node scripts/probe-switch.mjs && node scripts/probe-slider.mjs && node scripts/probe-panel.mjs && node scripts/probe-popover-width.mjs && node scripts/probe-api.mjs && node scripts/probe-api-live.mjs && node scripts/probe-tabs-overflow.mjs && node scripts/probe-stat-row.mjs && node scripts/probe-packaging.mjs && node scripts/probe-containment.mjs && node scripts/probe-popover-containment.mjs && node scripts/probe-popover-panel-width.mjs && node scripts/probe-theme-menu-overflow.mjs && node scripts/probe-shell.mjs && node scripts/probe-nav-trigger-tap-target.mjs && node scripts/probe-attachment-touch.mjs && node scripts/probe-dense-button.mjs && node scripts/probe-card-header.mjs && node scripts/probe-inline-edit.mjs && node scripts/probe-read-more.mjs && node scripts/probe-section-nav.mjs && node scripts/probe-attention.mjs",
+    "probe": "node scripts/probe-scale.mjs && node scripts/probe-switch.mjs && node scripts/probe-slider.mjs && node scripts/probe-panel.mjs && node scripts/probe-popover-width.mjs && node scripts/probe-api.mjs && node scripts/probe-api-live.mjs && node scripts/probe-tabs-overflow.mjs && node scripts/probe-stat-row.mjs && node scripts/probe-packaging.mjs && node scripts/probe-containment.mjs && node scripts/probe-popover-containment.mjs && node scripts/probe-popover-panel-width.mjs && node scripts/probe-theme-menu-overflow.mjs && node scripts/probe-shell.mjs && node scripts/probe-nav-trigger-tap-target.mjs && node scripts/probe-attachment-touch.mjs && node scripts/probe-dense-button.mjs && node scripts/probe-card-header.mjs && node scripts/probe-inline-edit.mjs && node scripts/probe-read-more.mjs && node scripts/probe-section-nav.mjs && node scripts/probe-attention.mjs && node scripts/probe-paged-window.mjs",
     "sync": "node scripts/sync.mjs",
     "visual": "node scripts/visual-docker.mjs",
     "visual:update": "node scripts/visual-docker.mjs --update-snapshots",