chat-layout 1.2.0-4 → 1.2.0-6

package/README.md

@@ -9,7 +9,7 @@ The current v2-style APIs are:
 - `Place`: place a single child at `start` / `center` / `end`
 - `ShrinkWrap`: search the narrowest width that keeps the current height stable
 - `MultilineText`: text layout with logical `align` or physical `physicalAlign`
-- `ChatRenderer` + `ListState`: virtualized chat rendering
+- `ListRenderer` + `ListState`: virtualized chat or timeline rendering
 - `memoRenderItem` / `memoRenderItemBy`: item render memoization
 
 ## Quick example
@@ -53,6 +53,29 @@ return row;
 
 See [example/chat.ts](./example/chat.ts) for a full chat example.
 
+## List insert animation
+
+`pushAll()` and `unshiftAll()` can opt into short-list insertion animations. They only animate when the previous rendered frame still had spare space below the last item; otherwise they fall back to the normal hard cut:
+
+```ts
+list.pushAll([nextMessage], {
+  distance: 24, // duration defaults to 220ms when animation options are present
+});
+
+list.unshiftAll([olderMessage], {
+  duration: 220,
+});
+```
+
+To make chat-style inserts automatically follow the latest visible edge, pass `followIfAtBoundary: true`. When the viewport was already pinned to that edge, the insert behaves like a conditional `jumpTo()` instead of combining with the enter animation:
+
+```ts
+list.pushAll([nextMessage], {
+  followIfAtBoundary: true,
+  duration: 220,
+});
+```
+
 ## Layout notes
 
 - `Flex` handles the main axis only. It shrink-wraps on the cross axis unless you opt into stretch behavior.

package/example/chat.ts

@@ -1,8 +1,8 @@
 import {
-  ChatRenderer,
   Flex,
   FlexItem,
   Fixed,
+  ListRenderer,
   ListState,
   MultilineText,
   PaddingBox,
@@ -221,6 +221,7 @@ const richReplyPreview: InlineSpan<C>[] = [
 
 let currentHover: ChatItem | undefined;
 const REPLACE_ANIMATION_DURATION = 320;
+const INSERT_ANIMATION_DURATION = 220;
 
 function revokeMessage(item: MessageItem): RevokedItem {
   return {
@@ -498,7 +499,9 @@ const list = new ListState<ChatItem>([
   },
   { id: 9, kind: "message", sender: "B", content: randomText(5) },
 ]);
-const renderer = new ChatRenderer(ctx, {
+const renderer = new ListRenderer(ctx, {
+  anchorMode: "bottom",
+  underflowAlign: "top",
   renderItem,
   list,
 });
@@ -510,6 +513,8 @@ function drawFrame(): void {
     maxIdx: Number.NaN,
     min: Number.NaN,
     max: Number.NaN,
+    canAutoFollowTop: false,
+    canAutoFollowBottom: false,
   };
   renderer.render(feedback);
 
@@ -630,21 +635,37 @@ function randomText(words: number): string {
 }
 
 button("unshift", () => {
-  list.unshift({
-    id: nextMessageId++,
-    kind: "message",
-    sender: Math.random() < 0.5 ? "A" : "B",
-    content: randomText(10 + Math.floor(200 * Math.random())),
-  });
+  list.unshiftAll(
+    [
+      {
+        id: nextMessageId++,
+        kind: "message",
+        sender: Math.random() < 0.5 ? "A" : "B",
+        content: randomText(10 + Math.floor(200 * Math.random())),
+      },
+    ],
+    {
+      duration: INSERT_ANIMATION_DURATION,
+      autoFollow: true,
+    },
+  );
 });
 
 button("push", () => {
-  list.push({
-    id: nextMessageId++,
-    kind: "message",
-    sender: Math.random() < 0.5 ? "A" : "B",
-    content: randomText(10 + Math.floor(200 * Math.random())),
-  });
+  list.pushAll(
+    [
+      {
+        id: nextMessageId++,
+        kind: "message",
+        sender: Math.random() < 0.5 ? "A" : "B",
+        content: randomText(10 + Math.floor(200 * Math.random())),
+      },
+    ],
+    {
+      distance: 24,
+      autoFollow: true,
+    },
+  );
 });
 
 button("jump middle", () => {

package/index.d.mts

@@ -19,6 +19,10 @@ interface RenderFeedback {
   min: number;
   /** Largest visible continuous item position, expressed in item coordinates rather than pixels. */
   max: number;
+  /** Whether the current viewport may auto-follow inserts at the visual top edge. */
+  canAutoFollowTop: boolean;
+  /** Whether the current viewport may auto-follow inserts at the visual bottom edge. */
+  canAutoFollowBottom: boolean;
 }
 /**
  * The main axis direction used by flex containers.
@@ -517,6 +521,16 @@ interface DeleteListItemAnimationOptions {
   /** Animation duration in milliseconds. */
   duration?: number;
 }
+interface InsertListItemsAnimationOptions {
+  /** Animation duration in milliseconds. */
+  duration?: number;
+  /** Enter offset in pixels measured from the final resting position. */
+  distance?: number;
+  /** Auto-follow the insertion edge when the viewport was already pinned there. */
+  autoFollow?: boolean;
+}
+type PushListItemsAnimationOptions = InsertListItemsAnimationOptions;
+type UnshiftListItemsAnimationOptions = InsertListItemsAnimationOptions;
 declare class ListState<T extends {}> {
   #private;
   /** Pixel offset from the anchored item edge. */
@@ -534,11 +548,11 @@ declare class ListState<T extends {}> {
   /** Prepends one or more items. */
   unshift(...items: T[]): void;
   /** Prepends an array of items. */
-  unshiftAll(items: T[]): void;
+  unshiftAll(items: T[], animation?: UnshiftListItemsAnimationOptions): void;
   /** Appends one or more items. */
   push(...items: T[]): void;
   /** Appends an array of items. */
-  pushAll(items: T[]): void;
+  pushAll(items: T[], animation?: PushListItemsAnimationOptions): void;
   /**
    * Updates an existing item by object identity.
    */
@@ -583,6 +597,10 @@ declare function memoRenderItemBy<C extends CanvasRenderingContext2D, T, K>(keyO
 };
 //#endregion
 //#region src/renderer/virtualized/base-types.d.ts
+type AutoFollowCapabilities = {
+  top: boolean;
+  bottom: boolean;
+};
 /** Per-item draw/hittest callbacks produced by the resolver. */
 type VirtualizedResolvedItem = {
   draw: (y: number) => boolean;
@@ -590,6 +608,16 @@ type VirtualizedResolvedItem = {
 };
 //#endregion
 //#region src/renderer/virtualized/solver.d.ts
+type ListAnchorMode = "top" | "bottom";
+type ListUnderflowAlign = "top" | "bottom";
+interface ListLayoutOptions {
+  anchorMode?: ListAnchorMode;
+  underflowAlign?: ListUnderflowAlign;
+}
+interface ResolvedListLayoutOptions {
+  anchorMode: ListAnchorMode;
+  underflowAlign: ListUnderflowAlign;
+}
 interface VisibleListState {
   position?: number;
   offset: number;
@@ -610,6 +638,7 @@ interface VisibleWindow<T> {
 }
 interface VisibleWindowResult<T> {
   normalizedState: NormalizedListState;
+  resolutionPath: number[];
   window: VisibleWindow<T>;
 }
 //#endregion
@@ -637,7 +666,7 @@ declare abstract class VirtualizedRenderer<C extends CanvasRenderingContext2D, T
   #private;
   static readonly MIN_JUMP_DURATION = 160;
   static readonly MAX_JUMP_DURATION = 420;
-  static readonly JUMP_DURATION_PER_ITEM = 28;
+  static readonly JUMP_DURATION_PER_PIXEL = 0.7;
   constructor(graphics: C, options: {
     renderItem: (item: T) => Node<C>;
     list: ListState<T>;
@@ -663,67 +692,71 @@ declare abstract class VirtualizedRenderer<C extends CanvasRenderingContext2D, T
     type: "click" | "auxclick" | "hover";
   }): boolean;
   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;
-  protected _renderVisibleWindow(window: VisibleWindow<VirtualizedResolvedItem>, feedback?: RenderFeedback): boolean;
+  protected _renderVisibleWindow(window: VisibleWindow<VirtualizedResolvedItem>, feedback?: RenderFeedback, extraShift?: number): boolean;
+  protected _readAutoFollowCapabilities(window: VisibleWindow<VirtualizedResolvedItem>, extraShift?: number): AutoFollowCapabilities;
   protected _readVisibleRange(top: number, height: number): {
     top: number;
     bottom: number;
   } | undefined;
-  protected _pruneReplacementAnimations(_window: VisibleWindow<unknown>): boolean;
-  protected _hittestVisibleWindow(window: VisibleWindow<VirtualizedResolvedItem>, test: HitTest): boolean;
-  protected _captureVisibleItemSnapshot(window: VisibleWindow<unknown>): void;
+  protected _pruneTransitionAnimations(_window: VisibleWindow<unknown>, now: number): boolean;
+  protected _hittestVisibleWindow(window: VisibleWindow<VirtualizedResolvedItem>, test: HitTest, extraShift?: number): boolean;
+  protected _captureVisibleItemSnapshot(solution: VisibleWindowResult<unknown>, extraShift?: number): void;
   protected _prepareRender(now: number): boolean;
   protected _finishRender(requestRedraw: boolean): boolean;
   protected _clampItemIndex(index: number): number;
   protected _getItemHeight(index: number): number;
+  protected _getItemHeightAt(index: number, now: number): number;
+  protected _readAnchorAt(now: number): number | undefined;
+  protected _restoreAnchor(anchor: number): void;
   protected _resolveItem(item: T, _index: number, now: number): {
     value: VirtualizedResolvedItem;
     height: number;
   };
-  protected _getAnchorAtOffset(index: number, offset: number): number;
   protected abstract _normalizeListState(state: VisibleListState): NormalizedListState;
-  protected abstract _resolveVisibleWindow(now: number): VisibleWindowResult<VirtualizedResolvedItem>;
-  protected abstract _readAnchor(state: NormalizedListState): number;
+  protected abstract _getLayoutOptions(): ResolvedListLayoutOptions;
+  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 _getAnimatedLayerOffset(slotHeight: number, nodeHeight: number): number;
 }
 //#endregion
-//#region src/renderer/virtualized/chat.d.ts
-/**
- * Virtualized renderer anchored to the bottom, suitable for chat-style UIs.
- */
-declare class ChatRenderer<C extends CanvasRenderingContext2D, T extends {}> extends VirtualizedRenderer<C, T> {
-  protected _resolveVisibleWindow(now: number): VisibleWindowResult<VirtualizedResolvedItem>;
-  protected _getDefaultJumpBlock(): NonNullable<JumpToOptions["block"]>;
-  protected _normalizeListState(state: VisibleListState): NormalizedListState;
-  protected _readAnchor(state: NormalizedListState): number;
-  protected _applyAnchor(anchor: number): void;
-  protected _getTargetAnchor(index: number, block: NonNullable<JumpToOptions["block"]>): number;
-  protected _getAnimatedLayerOffset(slotHeight: number, nodeHeight: number): number;
+//#region src/renderer/virtualized/list.d.ts
+interface ListRendererOptions<C extends CanvasRenderingContext2D, T extends {}> extends ListLayoutOptions {
+  renderItem: (item: T) => Node<C>;
+  list: ListState<T>;
 }
-//#endregion
-//#region src/renderer/virtualized/timeline.d.ts
 /**
- * Virtualized renderer anchored to the top, suitable for timeline-style UIs.
+ * Virtualized list renderer with configurable anchor semantics.
  */
-declare class TimelineRenderer<C extends CanvasRenderingContext2D, T extends {}> extends VirtualizedRenderer<C, T> {
-  protected _resolveVisibleWindow(now: number): VisibleWindowResult<VirtualizedResolvedItem>;
+declare class ListRenderer<C extends CanvasRenderingContext2D, T extends {}> extends VirtualizedRenderer<C, T> {
+  #private;
+  constructor(graphics: C, options: ListRendererOptions<C, T>);
+  protected _getLayoutOptions(): ResolvedListLayoutOptions;
+  protected _resolveVisibleWindowForState(state: VisibleListState, now: number): VisibleWindowResult<VirtualizedResolvedItem>;
   protected _getDefaultJumpBlock(): NonNullable<JumpToOptions["block"]>;
   protected _normalizeListState(state: VisibleListState): NormalizedListState;
-  protected _readAnchor(state: NormalizedListState): number;
+  protected _readAnchor(state: NormalizedListState, readItemHeight: (index: number) => number): number;
   protected _applyAnchor(anchor: number): void;
   protected _getTargetAnchor(index: number, block: NonNullable<JumpToOptions["block"]>): number;
-  protected _getAnimatedLayerOffset(_slotHeight: number, _nodeHeight: number): number;
 }
 //#endregion
-export { Axis, BaseRenderer, Box, ChatRenderer, ChildLayoutResult, Context, CrossAxisAlignment, DebugRenderer, DeleteListItemAnimationOptions, DynValue, Fixed, Flex, FlexContainerOptions, FlexItem, FlexItemOptions, FlexLayoutResult, Group, HitTest, InlineSpan, JumpToOptions, LayoutConstraints, LayoutRect, ListState, MainAxisAlignment, MainAxisSize, MultilineText, MultilineTextOptions, Node, PaddingBox, PhysicalTextAlign, Place, RenderFeedback, RendererOptions, ShrinkWrap, Text, TextAlign, TextEllipsisPosition, TextJustifyMode, TextJustifyOptions, TextOptions, TextOverflowMode, TextOverflowWrapMode, TextStyleOptions, TextWhiteSpaceMode, TextWordBreakMode, TimelineRenderer, 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, JumpToOptions, LayoutConstraints, LayoutRect, ListAnchorMode, ListLayoutOptions, 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 };
 //# sourceMappingURL=index.d.mts.map