@danxbot/ui 20.9.0 → 20.10.0

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

@@ -138,12 +138,32 @@ export interface BoardColumnProps<T> {
      * never colour or glyph alone (WCAG 1.4.1).
      */
     icon?: ReactNode;
+    /**
+     * DX-4540: the lane's real length when `column.items` holds only the cards
+     * loaded so far (a windowed lane, see the file header). The count badge, the
+     * empty-state decision and the WIP limit all read it instead of the loaded
+     * count, so a lane of 500 shows 500 while rendering 40. Omitted, they read
+     * `column.count` exactly as before.
+     *
+     * `null` is "the length is still being read" (a lane opening, or starting a
+     * new sort): the count shows a dash, and the lane is NOT empty — its cards
+     * are on their way, so the empty state stays away and the children (a
+     * `PagedWindowList` holding a loading placeholder) stay mounted.
+     */
+    total?: number | null;
+    /**
+     * 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, total, 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/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 held, across every held page. */
+    local: number;
+    /** Position in the whole list: `page * pageSize + index on the page`. */
+    global: number;
+}
+export interface PagedWindowListProps<T> {
+    /** The window to render — what `usePagedWindow` returned. */
+    window: 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>({ window: win, 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/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 { 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/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/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;

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

@@ -0,0 +1,2 @@
+export { PagedWindowStore, windowPageNumbers, type LoadPage, type LoadPageContext, type PageResponse, type PageSnapshot, type PageStatus, 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,111 @@
+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>>;
+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;
+}
+export interface PagedWindowSnapshot<T> {
+    /** 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>[];
+    /** Every item of every `ready` held page, in list order. At most `windowPages * pageSize`. */
+    items: readonly T[];
+}
+export interface PagedWindowOptions<T> {
+    pageSize: number;
+    /** How many pages are held at once. @default 3 */
+    windowPages?: number;
+    loadPage: LoadPage<T>;
+}
+/**
+ * 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 held;
+    private total;
+    private anchor;
+    /** The anchor the held pages were last synced to; differs from `anchor` only while frozen. */
+    private appliedAnchor;
+    private enabled;
+    private frozen;
+    private epoch;
+    private nextToken;
+    private snapshot;
+    private listeners;
+    constructor({ pageSize, windowPages, loadPage }: PagedWindowOptions<T>);
+    /**
+     * Replaced on every render by the React binding, so a consumer's loader 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.
+     */
+    setLoader(loadPage: LoadPage<T>): 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
+     * 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;
+    /** Off, nothing is held or requested. Back on, the window loads again. */
+    setEnabled(enabled: boolean): 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. */
+    invalidateAll(): void;
+    /** Load the first window. The binding calls it on mount, and again after a `stop`. */
+    start(): void;
+    /** Abort every request and release every held page. The binding calls it on unmount. */
+    stop(): void;
+    private pageCount;
+    /**
+     * Pages to hold now. 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;
+    private sync;
+    /** Start (or restart) a page's request; whatever was in flight is abandoned. */
+    private request;
+    private settle;
+    /** The list shrank: a held page past its end has nothing to show. */
+    private dropBeyondCount;
+    private dropAll;
+    private build;
+    private publish;
+}

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

@@ -0,0 +1,40 @@
+import { 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 `loadPage`'s identity alone does not:
+     * a loader closing over fresh state must not throw away what is held.
+     */
+    queryKey: string;
+    /**
+     * Off, nothing is held or requested (a hidden lane). Back on, the window
+     * loads again.
+     * @default true
+     */
+    enabled?: boolean;
+}
+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. */
+    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, queryKey, enabled, }: UsePagedWindowOptions<T>): PagedWindow<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "20.9.0",
+  "version": "20.10.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",