chat-layout 1.2.0-3 → 1.2.0-5

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 {
@@ -253,6 +254,13 @@ class ItemDetector extends Wrapper<C> {
       list.update(this.item, nextItem, {
         duration: REPLACE_ANIMATION_DURATION,
       });
+    } else if (test.type === "auxclick") {
+      if (!list.items.includes(this.item)) {
+        return true;
+      }
+      list.delete(this.item, {
+        duration: REPLACE_ANIMATION_DURATION,
+      });
     }
     return true;
   }
@@ -491,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,
 });
@@ -555,6 +565,19 @@ canvas.addEventListener("click", (e) => {
   }
 });
 
+canvas.addEventListener("contextmenu", (e) => {
+  e.preventDefault();
+  const { top, left } = canvas.getBoundingClientRect();
+  const result = renderer.hittest({
+    x: e.clientX - left,
+    y: e.clientY - top,
+    type: "auxclick",
+  });
+  if (!result) {
+    currentHover = undefined;
+  }
+});
+
 function randomEnglishText(words: number): string {
   const out: string[] = [];
   for (let i = 0; i < words; i += 1) {
@@ -610,21 +633,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,
+      followIfAtBoundary: 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,
+      followIfAtBoundary: true,
+    },
+  );
 });
 
 button("jump middle", () => {

package/index.d.mts

@@ -513,6 +513,20 @@ interface UpdateListItemAnimationOptions {
   /** Animation duration in milliseconds. */
   duration?: number;
 }
+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. */
+  followIfAtBoundary?: boolean;
+}
+type PushListItemsAnimationOptions = InsertListItemsAnimationOptions;
+type UnshiftListItemsAnimationOptions = InsertListItemsAnimationOptions;
 declare class ListState<T extends {}> {
   #private;
   /** Pixel offset from the anchored item edge. */
@@ -530,15 +544,23 @@ 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.
    */
   update(targetItem: T, nextItem: T, animation?: UpdateListItemAnimationOptions): void;
+  /**
+   * Starts deleting an existing item by object identity.
+   */
+  delete(item: T, animation?: DeleteListItemAnimationOptions): void;
+  /**
+   * Finalizes a pending delete by removing the item from the list.
+   */
+  finalizeDelete(item: T): void;
   /**
    * Sets the current anchor item and pixel offset.
    */
@@ -570,7 +592,24 @@ declare function memoRenderItemBy<C extends CanvasRenderingContext2D, T, K>(keyO
   resetKey: (key: K) => boolean;
 };
 //#endregion
+//#region src/renderer/virtualized/base-types.d.ts
+/** Per-item draw/hittest callbacks produced by the resolver. */
+type VirtualizedResolvedItem = {
+  draw: (y: number) => boolean;
+  hittest: (test: HitTest, y: number) => boolean;
+};
+//#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;
@@ -589,6 +628,11 @@ interface VisibleWindow<T> {
   drawList: VisibleWindowEntry<T>[];
   shift: number;
 }
+interface VisibleWindowResult<T> {
+  normalizedState: NormalizedListState;
+  resolutionPath: number[];
+  window: VisibleWindow<T>;
+}
 //#endregion
 //#region src/renderer/virtualized/base.d.ts
 /**
@@ -604,10 +648,6 @@ interface JumpToOptions {
   /** Called after the jump completes or finishes animating. */
   onComplete?: () => void;
 }
-type VirtualizedResolvedItem<C extends CanvasRenderingContext2D> = {
-  draw: (y: number) => boolean;
-  hittest: (test: HitTest, y: number) => boolean;
-};
 /**
  * Shared base class for virtualized list renderers.
  */
@@ -618,7 +658,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>;
@@ -636,14 +676,15 @@ declare abstract class VirtualizedRenderer<C extends CanvasRenderingContext2D, T
   /** Replaces the current item collection. */
   set items(value: T[]);
   /** Renders the current visible window. */
-  abstract render(feedback?: RenderFeedback): boolean;
+  render(feedback?: RenderFeedback): boolean;
   /** Hit-tests the current visible window. */
-  abstract hittest(test: {
+  hittest(test: {
     x: number;
     y: number;
     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.
@@ -651,57 +692,54 @@ declare abstract class VirtualizedRenderer<C extends CanvasRenderingContext2D, T
   jumpTo(index: number, options?: JumpToOptions): void;
   protected _resetRenderFeedback(feedback?: RenderFeedback): void;
   protected _accumulateRenderFeedback(feedback: RenderFeedback, idx: number, top: number, height: number): void;
-  protected _renderDrawList(list: VisibleWindow<VirtualizedResolvedItem<C>>["drawList"], shift: number, feedback?: RenderFeedback): boolean;
-  protected _renderVisibleWindow(window: VisibleWindow<VirtualizedResolvedItem<C>>, feedback?: RenderFeedback): boolean;
-  protected _hittestVisibleWindow(window: VisibleWindow<VirtualizedResolvedItem<C>>, test: HitTest): boolean;
-  protected _prepareRender(): boolean;
+  protected _renderDrawList(list: VisibleWindow<VirtualizedResolvedItem>["drawList"], shift: number, feedback?: RenderFeedback): boolean;
+  protected _renderVisibleWindow(window: VisibleWindow<VirtualizedResolvedItem>, feedback?: RenderFeedback, extraShift?: number): boolean;
+  protected _readVisibleRange(top: number, height: number): {
+    top: number;
+    bottom: number;
+  } | undefined;
+  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<C>;
+    value: VirtualizedResolvedItem;
     height: number;
   };
-  protected _getAnchorAtOffset(index: number, offset: number): number;
   protected abstract _normalizeListState(state: VisibleListState): NormalizedListState;
-  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> {
-  #private;
-  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;
-  render(feedback?: RenderFeedback): boolean;
-  hittest(test: HitTest): boolean;
+//#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> {
+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;
-  render(feedback?: RenderFeedback): boolean;
-  hittest(test: HitTest): boolean;
 }
 //#endregion
-export { Axis, BaseRenderer, Box, ChatRenderer, ChildLayoutResult, Context, CrossAxisAlignment, DebugRenderer, 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