chat-layout 1.2.0 → 1.3.0-0

package/example/chat.ts

@@ -673,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

@@ -533,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;
@@ -580,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
@@ -665,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.
  */
@@ -712,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;
@@ -756,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
@@ -776,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, initRenderFeedback, 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);
 	}
@@ -4112,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");
@@ -4132,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") {
@@ -5404,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;
@@ -5428,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({
@@ -5454,24 +5518,6 @@ 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;
 		initRenderFeedback(feedback);
@@ -5672,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