@danxbot/ui 20.11.0 → 20.12.1

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

@@ -0,0 +1,31 @@
+import type { ReactNode, Ref } from "react";
+import type { BlockStatus } from "../../lib/paged-window/layout";
+export interface PageBlockProps {
+    page: number;
+    status: BlockStatus;
+    /** The cards of a `ready` page. Ignored for every other status: they have none to show. */
+    children?: ReactNode;
+    /** How many cards a `ready` page shows (`data-count`, which the pitch measurement reads). */
+    count: number;
+    /** The height the page holds when it has no cards: 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 ONE ELEMENT A PAGE IS, in every state. A page turns from placeholder to
+ * cards (a load), to placeholder again (a drop) and to an error row and back
+ * without this element being replaced: it is the same component type at the same
+ * key, so React keeps the same DOM node. That is what keeps the browser's scroll
+ * anchoring on the element under the viewport and keeps the observers attached
+ * (visibility and pitch) instead of detaching and re-attaching on every change.
+ * What changes is only what it holds and how it is drawn: the cards of a ready
+ * page, otherwise the page's height (and, while loading, faint rows; on failure,
+ * a Retry row).
+ */
+export declare function PageBlock({ page, status, children, count, height, pitch, blockRef, errorText, retryText, onRetry, }: PageBlockProps): import("react").JSX.Element;

package/dist/types/index.d.ts

@@ -113,10 +113,10 @@ export { DragDrop, DragDropContainer, DragDropItem, DragDropHandle, DragDropSurf
 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, 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, moveAnchor, type BoardModel, type MoveAnchor, type UseBoardResult, } from "./lib/board";
+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, 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 { 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/board/anchor.d.ts

@@ -10,26 +10,42 @@
  *
  * `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.
+ * `rest[to.index]`, where `rest` is the destination's loaded cards without the
+ * moved one. ONE neighbour is named, because a server places a card relative to
+ * one: the card it lands directly above (`beforeId`) whenever there is one, and
+ * only at the end of the loaded run, where nothing is below, the card it lands
+ * directly below (`afterId`). An empty destination names nothing.
  *
  * 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;
-}
+/**
+ * EXACTLY ONE placement field is set — a server's lane-move takes one — or none
+ * for an empty destination:
+ *   beforeId  the moved card lands directly above this loaded card
+ *   afterId   it lands directly below this one: only when it lands after the last
+ *             loaded card, where nothing is below to name
+ *   edge      it goes to the very top or bottom of the whole column
+ */
+export type MoveAnchor = {
+    beforeId: BoardItemId;
+    afterId?: never;
+    edge?: never;
+} | {
+    afterId: BoardItemId;
+    beforeId?: never;
+    edge?: never;
+} | {
+    edge: BoardEdge;
+    beforeId?: never;
+    afterId?: never;
+} | {
+    beforeId?: never;
+    afterId?: never;
+    edge?: never;
+};
 /**
  * @param destinationItems the destination column's LOADED cards (the moved card
  *   may be among them, for a same-column move).

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

@@ -11,5 +11,6 @@
 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 { columnLength, positionInColumn } from "./position";
 export { applyBoardMoves, resolveMove, type ResolveMoveContext, type ResolvedMove, } from "./move";
 export { useBoard, type UseBoardResult } from "./use-board";

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

@@ -146,6 +146,15 @@ export declare function resolveMove<T>(context: ResolveMoveContext<T>, request:
  * column membership on every subsequent `buildBoardModel` call, and
  * `buildBoardModel` only ever reads WITHIN-column order.
  *
+ * `to.edge` IS NOT APPLIED HERE. This arranges the cards it was given, and in a
+ * windowed column an edge move lands OUTSIDE the cards that are loaded — at the
+ * top or bottom of a list this function cannot see — so the index it would
+ * splice at is only the nearest loaded position, not the place the card is
+ * going. A consumer of a windowed column sends the move to its server (see
+ * `moveAnchor`) and re-reads the affected pages (`invalidateAll`); it does not
+ * apply an edge move locally. In a column with every card loaded the edge IS
+ * the index, and this function is exactly right.
+ *
  * NEVER WRITES A FIELD ON ANY ITEM — ONLY REPOSITIONS. `BoardAccessors` has
  * no setter, on purpose (the file header on `types.ts` — items are opaque),
  * so this function CANNOT change what `getColumnId` reports for a moved

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

@@ -0,0 +1,22 @@
+/**
+ * ==== COLUMN POSITION ====
+ *
+ * Two facts about a column that three callers each need and must not each work
+ * out for themselves (DX-4540): how long the column really is, and where in the
+ * whole column a loaded card sits. A windowed column holds only a few pages of
+ * a longer list, so the cards loaded are not the column.
+ *
+ * `buildBoardModel` decides the length once (the model's `count`); `resolveMove`
+ * works from the column DEFINITIONS before any model exists and must decide
+ * "is this card already at that edge" with the same rule; and the move menu
+ * decides what to offer from a card's place in the column. All three read these.
+ */
+import type { BoardColumnDef } from "./types";
+/**
+ * The column's length: its `total` when the definition gave a number, otherwise
+ * the cards loaded (`total` absent means every card is loaded; `null` means the
+ * length is still being read, so the loaded cards are all that is known).
+ */
+export declare function columnLength(def: Pick<BoardColumnDef, "total"> | undefined, loaded: number): number;
+/** The place in the whole column of the loaded card at `index`: the window's offset plus the index. */
+export declare function positionInColumn(def: Pick<BoardColumnDef, "offset"> | undefined, index: number): number;

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

@@ -0,0 +1,21 @@
+import type { PageSnapshot } from "./store";
+/**
+ * What a page's block is showing. One name for every case, so the list renders
+ * ONE kind of block and only this changes:
+ *   ready    the page's cards are shown
+ *   loading  held, its request is in flight
+ *   error    held, its request failed
+ *   waiting  held and ready, but past a hole in the loaded run — not shown until
+ *            the page that closes the hole arrives (see the store header)
+ *   unheld   outside the window: empty space of the right height
+ */
+export type BlockStatus = "ready" | "loading" | "error" | "waiting" | "unheld";
+export declare function blockStatus<T>(held: PageSnapshot<T> | undefined): BlockStatus;
+/**
+ * How many page blocks to render. One per page of the list; before the first
+ * response the length is unknown but page 0 is being asked for, and one block
+ * stands in for it, so a new query does not flash an empty list.
+ */
+export declare function blockCountFor(pageCount: number, heldPageCount: number): number;
+/** The height of a page's placeholder: the items it holds (the last page is short) times one item's height. */
+export declare function placeholderHeight(page: number, pageSize: number, total: number, pitch: number): number;

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

@@ -76,6 +76,12 @@ export declare class PagedWindowStore<T> {
     private epoch;
     private nextToken;
     private countRequest;
+    /** Answers that arrived while frozen, applied in arrival order on thaw. */
+    private heldAnswers;
+    /** Pages whose refresh was asked for while frozen. */
+    private queuedPages;
+    /** The length's refresh (count mode) was asked for while frozen. */
+    private queuedCount;
     private countError;
     private snapshot;
     private listeners;
@@ -92,9 +98,12 @@ export declare class PagedWindowStore<T> {
     /** 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.
+     * While true nothing about the window changes: it neither loads nor drops
+     * pages, starts no refresh and applies no answer, whatever the anchor or the
+     * total does (all of it waits for the thaw). 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. Only `reset()` ignores it — a query change is a
+     * different list.
      */
     setFrozen(frozen: boolean): void;
     /** `count` holds and requests no cards, only the length (see the file header). */
@@ -121,11 +130,18 @@ 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. */
+    private reconcile;
+    /** Everything the frozen window put off, in the order the header promises. */
+    private thaw;
     /** Start (or restart) a page's request; whatever was in flight is abandoned. */
     private request;
     private settle;
+    /** Record an answer on its page — no window change, no notification: callers sync once. */
+    private applyPage;
     private requestCount;
     private settleCount;
+    private applyCount;
     private abortCount;
     private dropAll;
     /**

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

@@ -16,6 +16,17 @@
  *
  * 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.
+ *
+ * NOTHING IS EVER RESET, AND THAT IS DELIBERATE. A new query (another sort, a
+ * different time range) lists the same kind of card, so what was learned about
+ * its height still holds; clearing it would snap every placeholder back to the
+ * estimate and make the first screen of the new query jump. The measurement is
+ * only a sizing aid for space no card occupies, and the mean keeps correcting
+ * itself from every page that is shown.
+ *
+ * A block whose size does not change when it turns from placeholder to cards
+ * (or back) fires no resize, so its reading is picked up at the next size change;
+ * a placeholder is sized from the estimate in the first place.
  */
 export declare function useMeasuredPitch(estimated: number): {
     pitch: number;

package/package.json

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

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

@@ -1,21 +0,0 @@
-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;