chat-layout 1.2.0-9 → 1.3.0-0

package/README.md

@@ -194,6 +194,24 @@ Type-check:
 bun run typecheck
 ```
 
+Run tests:
+
+```bash
+bun run test
+```
+
+Run tests with coverage:
+
+```bash
+bun run test:coverage
+```
+
+Run the local verification bundle:
+
+```bash
+bun run check
+```
+
 Build distributable files:
 
 ```bash

package/example/chat.ts

@@ -10,13 +10,13 @@ import {
   ShrinkWrap,
   Text,
   Wrapper,
+  initRenderFeedback,
   memoRenderItem,
   type Context,
   type DynValue,
   type HitTest,
   type InlineSpan,
   type Node,
-  type RenderFeedback,
 } from "chat-layout";
 
 const sampleWords = [
@@ -507,16 +507,9 @@ const renderer = new ListRenderer(ctx, {
 });
 renderer.padding = { top: 32, bottom: 32 };
 let nextMessageId = list.items.length + 1;
+const feedback = initRenderFeedback();
 
 function drawFrame(): void {
-  const feedback: RenderFeedback = {
-    minIdx: Number.NaN,
-    maxIdx: Number.NaN,
-    min: Number.NaN,
-    max: Number.NaN,
-    canAutoFollowTop: false,
-    canAutoFollowBottom: false,
-  };
   renderer.render(feedback);
 
   ctx.save();
@@ -680,17 +673,17 @@ button("push", () => {
 });
 
 button("jump middle", () => {
-  renderer.jumpTo(Math.floor(list.items.length / 2));
+  list.scrollTo(Math.floor(list.items.length / 2));
 });
 
 button("jump middle (center)", () => {
-  renderer.jumpTo(Math.floor(list.items.length / 2), {
+  list.scrollTo(Math.floor(list.items.length / 2), {
     block: "center",
   });
 });
 
 button("jump latest (no anim)", () => {
-  renderer.jumpTo(list.items.length - 1, {
+  list.scrollTo(list.items.length - 1, {
     animated: false,
   });
 });

package/index.d.mts

@@ -24,6 +24,10 @@ interface RenderFeedback {
   /** Whether the current viewport may auto-follow inserts at the visual bottom edge. */
   canAutoFollowBottom: boolean;
 }
+/**
+ * Creates or resets a render feedback object to its default empty state.
+ */
+declare function initRenderFeedback(feedback?: Partial<RenderFeedback>): RenderFeedback;
 /**
  * The main axis direction used by flex containers.
  */
@@ -529,6 +533,16 @@ interface InsertListItemsAnimationOptions {
 }
 type PushListItemsAnimationOptions = InsertListItemsAnimationOptions;
 type UnshiftListItemsAnimationOptions = InsertListItemsAnimationOptions;
+interface ScrollToOptions {
+  /** Whether to animate the jump. Defaults to `true`. */
+  animated?: boolean;
+  /** Which edge of the item should align with the viewport. */
+  block?: "start" | "center" | "end";
+  /** Animation duration in milliseconds. */
+  duration?: number;
+  /** Called after the scroll completes or finishes animating. */
+  onComplete?: () => void;
+}
 type ListScrollMutationSource = "external" | "internal";
 type ListScrollStatePatch = {
   position?: number | undefined;
@@ -576,6 +590,16 @@ declare class ListState<T extends {}> {
   reset(items?: T[]): void;
   /** Applies a relative pixel scroll delta. */
   applyScroll(delta: number): void;
+  /** Scrolls the viewport to the requested item index. */
+  scrollTo(index: number, options?: ScrollToOptions): void;
+  /**
+   * Scrolls the viewport to the visual top edge and arms top auto-follow immediately.
+   */
+  scrollToTop(options?: ScrollToOptions): void;
+  /**
+   * Scrolls the viewport to the visual bottom edge and arms bottom auto-follow immediately.
+   */
+  scrollToBottom(options?: ScrollToOptions): void;
   [WRITE_LIST_SCROLL_STATE](patch: ListScrollStatePatch, source: ListScrollMutationSource): void;
 }
 //#endregion
@@ -661,19 +685,6 @@ type VirtualizedResolvedItem = {
 };
 //#endregion
 //#region src/renderer/virtualized/base.d.ts
-/**
- * Options for programmatic scrolling to a target item.
- */
-interface JumpToOptions {
-  /** Whether to animate the jump. Defaults to `true`. */
-  animated?: boolean;
-  /** Which edge of the item should align with the viewport. */
-  block?: "start" | "center" | "end";
-  /** Animation duration in milliseconds. */
-  duration?: number;
-  /** Called after the jump completes or finishes animating. */
-  onComplete?: () => void;
-}
 /**
  * Shared base class for virtualized list renderers.
  */
@@ -708,18 +719,6 @@ declare abstract class VirtualizedRenderer<C extends CanvasRenderingContext2D, T
   protected _readListState(): VisibleListState;
   protected _resolveVisibleWindow(now: number): VisibleWindowResult<VirtualizedResolvedItem>;
   protected _commitListState(state: NormalizedListState): void;
-  /**
-   * Scrolls the viewport to the requested item index.
-   */
-  jumpTo(index: number, options?: JumpToOptions): void;
-  /**
-   * Scrolls the viewport to the visual top edge and arms top auto-follow immediately.
-   */
-  jumpToTop(options?: JumpToOptions): void;
-  /**
-   * Scrolls the viewport to the visual bottom edge and arms bottom auto-follow immediately.
-   */
-  jumpToBottom(options?: JumpToOptions): void;
   protected _resetRenderFeedback(feedback?: RenderFeedback): void;
   protected _accumulateRenderFeedback(feedback: RenderFeedback, idx: number, top: number, height: number): void;
   protected _renderDrawList(list: VisibleWindow<VirtualizedResolvedItem>["drawList"], shift: number, feedback?: RenderFeedback): boolean;
@@ -752,8 +751,8 @@ declare abstract class VirtualizedRenderer<C extends CanvasRenderingContext2D, T
   protected abstract _resolveVisibleWindowForState(state: VisibleListState, now: number): VisibleWindowResult<VirtualizedResolvedItem>;
   protected abstract _readAnchor(state: NormalizedListState, readItemHeight: (index: number) => number): number;
   protected abstract _applyAnchor(anchor: number): void;
-  protected abstract _getDefaultJumpBlock(): NonNullable<JumpToOptions["block"]>;
-  protected abstract _getTargetAnchor(index: number, block: NonNullable<JumpToOptions["block"]>): number;
+  protected abstract _getDefaultJumpBlock(): NonNullable<ScrollToOptions["block"]>;
+  protected abstract _getTargetAnchor(index: number, block: NonNullable<ScrollToOptions["block"]>): number;
   protected _getViewportMetrics(): ListViewportMetrics;
 }
 //#endregion
@@ -772,12 +771,12 @@ declare class ListRenderer<C extends CanvasRenderingContext2D, T extends {}> ext
   set padding(value: ListPadding);
   protected _getLayoutOptions(): ResolvedListLayoutOptions;
   protected _resolveVisibleWindowForState(state: VisibleListState, now: number): VisibleWindowResult<VirtualizedResolvedItem>;
-  protected _getDefaultJumpBlock(): NonNullable<JumpToOptions["block"]>;
+  protected _getDefaultJumpBlock(): NonNullable<ScrollToOptions["block"]>;
   protected _normalizeListState(state: VisibleListState): NormalizedListState;
   protected _readAnchor(state: NormalizedListState, readItemHeight: (index: number) => number): number;
   protected _applyAnchor(anchor: number): void;
-  protected _getTargetAnchor(index: number, block: NonNullable<JumpToOptions["block"]>): number;
+  protected _getTargetAnchor(index: number, block: NonNullable<ScrollToOptions["block"]>): number;
 }
 //#endregion
-export { Axis, BaseRenderer, Box, ChildLayoutResult, Context, CrossAxisAlignment, DebugRenderer, DeleteListItemAnimationOptions, DynValue, Fixed, Flex, FlexContainerOptions, FlexItem, FlexItemOptions, FlexLayoutResult, Group, HitTest, InlineSpan, InsertListItemsAnimationOptions, JumpToOptions, LayoutConstraints, LayoutRect, ListAnchorMode, ListLayoutOptions, ListPadding, ListRenderer, ListRendererOptions, ListState, ListUnderflowAlign, MainAxisAlignment, MainAxisSize, MultilineText, MultilineTextOptions, Node, PaddingBox, PhysicalTextAlign, Place, PushListItemsAnimationOptions, RenderFeedback, RendererOptions, ShrinkWrap, Text, TextAlign, TextEllipsisPosition, TextJustifyMode, TextJustifyOptions, TextOptions, TextOverflowMode, TextOverflowWrapMode, TextStyleOptions, TextWhiteSpaceMode, TextWordBreakMode, UnshiftListItemsAnimationOptions, UpdateListItemAnimationOptions, VirtualizedRenderer, Wrapper, memoRenderItem, memoRenderItemBy };
+export { Axis, BaseRenderer, Box, ChildLayoutResult, Context, CrossAxisAlignment, DebugRenderer, DeleteListItemAnimationOptions, DynValue, Fixed, Flex, FlexContainerOptions, FlexItem, FlexItemOptions, FlexLayoutResult, Group, HitTest, InlineSpan, InsertListItemsAnimationOptions, LayoutConstraints, LayoutRect, ListAnchorMode, ListLayoutOptions, ListPadding, ListRenderer, ListRendererOptions, ListState, ListUnderflowAlign, MainAxisAlignment, MainAxisSize, MultilineText, MultilineTextOptions, Node, PaddingBox, PhysicalTextAlign, Place, PushListItemsAnimationOptions, RenderFeedback, RendererOptions, ScrollToOptions, ShrinkWrap, Text, TextAlign, TextEllipsisPosition, TextJustifyMode, TextJustifyOptions, TextOptions, TextOverflowMode, TextOverflowWrapMode, TextStyleOptions, TextWhiteSpaceMode, TextWordBreakMode, UnshiftListItemsAnimationOptions, UpdateListItemAnimationOptions, VirtualizedRenderer, Wrapper, initRenderFeedback, memoRenderItem, memoRenderItemBy };
 //# sourceMappingURL=index.d.mts.map

package/index.mjs

@@ -3576,11 +3576,13 @@ var DebugRenderer = class extends BaseRenderer {
 //#endregion
 //#region src/renderer/list-state.ts
 const listStateChangeQueues = /* @__PURE__ */ new WeakMap();
+const listScrollCommandQueues = /* @__PURE__ */ new WeakMap();
 const listScrollMutations = /* @__PURE__ */ new WeakMap();
 const WRITE_LIST_SCROLL_STATE = Symbol("writeListScrollState");
 const FINALIZE_LIST_DELETE = Symbol("finalizeListDelete");
 const LIST_STATE_CHANGE_TIME = Symbol("listStateChangeTime");
 const LIST_STATE_CHANGE_SNAPSHOT = Symbol("listStateChangeSnapshot");
+const LIST_SCROLL_COMMAND_TIME = Symbol("listScrollCommandTime");
 function normalizePosition(value) {
 	return typeof value === "number" && Number.isFinite(value) ? Math.trunc(value) : void 0;
 }
@@ -3616,6 +3618,14 @@ function writeInternalListScrollState(list, state) {
 function finalizeInternalListDelete(list, item) {
 	list[FINALIZE_LIST_DELETE](item);
 }
+function normalizeScrollToOptions(options) {
+	const normalized = {};
+	if (typeof options?.animated === "boolean") normalized.animated = options.animated;
+	if (options?.block === "start" || options?.block === "center" || options?.block === "end") normalized.block = options.block;
+	if (options?.duration != null && Number.isFinite(options.duration)) normalized.duration = options.duration;
+	if (typeof options?.onComplete === "function") normalized.onComplete = options.onComplete;
+	return normalized;
+}
 function enqueueListStateChange(list, change) {
 	const key = list;
 	let queue = listStateChangeQueues.get(key);
@@ -3638,6 +3648,20 @@ function enqueueListStateChange(list, change) {
 	});
 	queue.push(timestampedChange);
 }
+function enqueueListScrollCommand(list, command) {
+	const key = list;
+	let queue = listScrollCommandQueues.get(key);
+	if (queue == null) {
+		queue = [];
+		listScrollCommandQueues.set(key, queue);
+	}
+	const timestampedCommand = command;
+	Object.defineProperty(timestampedCommand, LIST_SCROLL_COMMAND_TIME, {
+		value: performance.now(),
+		configurable: true
+	});
+	queue.push(timestampedCommand);
+}
 function drainInternalListStateChanges(list) {
 	const key = list;
 	const queue = listStateChangeQueues.get(key);
@@ -3645,12 +3669,22 @@ function drainInternalListStateChanges(list) {
 	listStateChangeQueues.delete(key);
 	return queue;
 }
+function drainInternalListScrollCommands(list) {
+	const key = list;
+	const queue = listScrollCommandQueues.get(key);
+	if (queue == null || queue.length === 0) return [];
+	listScrollCommandQueues.delete(key);
+	return queue;
+}
 function readInternalListStateChangeTime(change) {
 	return change[LIST_STATE_CHANGE_TIME];
 }
 function readInternalListStateChangeSnapshot(change) {
 	return change[LIST_STATE_CHANGE_SNAPSHOT];
 }
+function readInternalListScrollCommandTime(command) {
+	return command[LIST_SCROLL_COMMAND_TIME];
+}
 function isObjectIdentityCandidate(value) {
 	return typeof value === "object" && value !== null || typeof value === "function";
 }
@@ -3834,6 +3868,34 @@ var ListState = class {
 	applyScroll(delta) {
 		this.#writeScrollState({ offset: this.#offset + delta }, "external");
 	}
+	/** Scrolls the viewport to the requested item index. */
+	scrollTo(index, options = {}) {
+		enqueueListScrollCommand(this, {
+			type: "index",
+			index,
+			options: normalizeScrollToOptions(options)
+		});
+	}
+	/**
+	* Scrolls the viewport to the visual top edge and arms top auto-follow immediately.
+	*/
+	scrollToTop(options = {}) {
+		enqueueListScrollCommand(this, {
+			type: "boundary",
+			boundary: "top",
+			options: normalizeScrollToOptions(options)
+		});
+	}
+	/**
+	* Scrolls the viewport to the visual bottom edge and arms bottom auto-follow immediately.
+	*/
+	scrollToBottom(options = {}) {
+		enqueueListScrollCommand(this, {
+			type: "boundary",
+			boundary: "bottom",
+			options: normalizeScrollToOptions(options)
+		});
+	}
 	[WRITE_LIST_SCROLL_STATE](patch, source) {
 		this.#writeScrollState(patch, source);
 	}
@@ -3918,6 +3980,21 @@ function memoRenderItemBy(keyOf, renderItem, options = {}) {
 	});
 }
 //#endregion
+//#region src/types.ts
+/**
+* Creates or resets a render feedback object to its default empty state.
+*/
+function initRenderFeedback(feedback = {}) {
+	const target = feedback;
+	target.minIdx = NaN;
+	target.maxIdx = NaN;
+	target.min = NaN;
+	target.max = NaN;
+	target.canAutoFollowTop = false;
+	target.canAutoFollowBottom = false;
+	return target;
+}
+//#endregion
 //#region src/renderer/virtualized/frame-session.ts
 function prepareFrameSession(params) {
 	let solution = params.resolveVisibleWindow(params.now);
@@ -4097,16 +4174,16 @@ var JumpController = class JumpController {
 	commit(state) {
 		this.#lastHandledScrollMutationVersion = this.#options.readScrollMutation().version;
 	}
-	jumpTo(index, options = {}) {
+	jumpTo(index, options = {}, now = getNow()) {
 		this.#clearPendingTransitionSettleReconcile();
 		this.#clearPendingPostJumpBoundary();
 		if (this.#options.getItemCount() === 0) {
 			this.#cancelJumpAnimation();
 			return;
 		}
-		this.#startJumpToIndex(index, options);
+		this.#startJumpToIndex(index, options, now);
 	}
-	jumpToBoundary(boundary, options = {}) {
+	jumpToBoundary(boundary, options = {}, now = getNow()) {
 		this.#clearPendingTransitionSettleReconcile();
 		this.#clearPendingPostJumpBoundary();
 		this.#armAutoFollowBoundary(boundary, "jump-to-boundary");
@@ -4117,7 +4194,7 @@ var JumpController = class JumpController {
 		this.#startJumpToIndex(boundary === "bottom" ? this.#options.getItemCount() - 1 : 0, {
 			...options,
 			block: boundary === "bottom" ? "end" : "start"
-		});
+		}, now);
 	}
 	beginAutoFollowBoundaryObservation(boundary) {
 		if (boundary === "top") {
@@ -5389,8 +5466,9 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 	/** Renders the current visible window. */
 	render(feedback) {
 		this.#drainPendingListStateChanges();
-		this.#jumpController.beforeFrame();
 		this.#jumpController.noteViewportWidth(this.graphics.canvas.clientWidth);
+		this.#drainPendingListScrollCommands();
+		this.#jumpController.beforeFrame();
 		const now = getNow();
 		const keepAnimating = this._prepareRender(now);
 		const { clientWidth: viewportWidth, clientHeight: viewportHeight } = this.graphics.canvas;
@@ -5413,8 +5491,9 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 	/** Hit-tests the current visible window. */
 	hittest(test) {
 		this.#drainPendingListStateChanges();
-		this.#jumpController.beforeFrame();
 		this.#jumpController.noteViewportWidth(this.graphics.canvas.clientWidth);
+		this.#drainPendingListScrollCommands();
+		this.#jumpController.beforeFrame();
 		const now = getNow();
 		this.#transitionController.settle(now, this.#getTransitionLifecycleAdapter());
 		const frame = prepareFrameSession({
@@ -5439,32 +5518,9 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 		writeInternalListScrollState(this.options.list, state);
 		this.#jumpController.commit(state);
 	}
-	/**
-	* Scrolls the viewport to the requested item index.
-	*/
-	jumpTo(index, options = {}) {
-		this.#jumpController.jumpTo(index, options);
-	}
-	/**
-	* Scrolls the viewport to the visual top edge and arms top auto-follow immediately.
-	*/
-	jumpToTop(options = {}) {
-		this.#jumpController.jumpToBoundary("top", options);
-	}
-	/**
-	* Scrolls the viewport to the visual bottom edge and arms bottom auto-follow immediately.
-	*/
-	jumpToBottom(options = {}) {
-		this.#jumpController.jumpToBoundary("bottom", options);
-	}
 	_resetRenderFeedback(feedback) {
 		if (feedback == null) return;
-		feedback.minIdx = NaN;
-		feedback.maxIdx = NaN;
-		feedback.min = NaN;
-		feedback.max = NaN;
-		feedback.canAutoFollowTop = false;
-		feedback.canAutoFollowBottom = false;
+		initRenderFeedback(feedback);
 	}
 	_accumulateRenderFeedback(feedback, idx, top, height) {
 		const visibleRange = this._readVisibleRange(top, height);
@@ -5662,6 +5718,17 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 			for (const change of changes) this.#handleListStateChange(change, readInternalListStateChangeTime(change), readInternalListStateChangeSnapshot(change));
 		}
 	}
+	#handleListScrollCommand(command, now) {
+		if (command.type === "boundary") {
+			this.#jumpController.jumpToBoundary(command.boundary, command.options, now);
+			return;
+		}
+		this.#jumpController.jumpTo(command.index, command.options, now);
+	}
+	#drainPendingListScrollCommands() {
+		const commands = drainInternalListScrollCommands(this.options.list);
+		for (const command of commands) this.#handleListScrollCommand(command, readInternalListScrollCommandTime(command));
+	}
 };
 //#endregion
 //#region src/renderer/virtualized/anchor-model.ts
@@ -5780,6 +5847,6 @@ var ListRenderer = class extends VirtualizedRenderer {
 	}
 };
 //#endregion
-export { BaseRenderer, DebugRenderer, Fixed, Flex, FlexItem, Group, ListRenderer, ListState, MultilineText, PaddingBox, Place, ShrinkWrap, Text, VirtualizedRenderer, Wrapper, memoRenderItem, memoRenderItemBy };
+export { BaseRenderer, DebugRenderer, Fixed, Flex, FlexItem, Group, ListRenderer, ListState, MultilineText, PaddingBox, Place, ShrinkWrap, Text, VirtualizedRenderer, Wrapper, initRenderFeedback, memoRenderItem, memoRenderItemBy };
 
 //# sourceMappingURL=index.mjs.map