chat-layout 1.2.0-5 → 1.2.0-7

package/README.md

@@ -67,11 +67,11 @@ list.unshiftAll([olderMessage], {
 });
 ```
 
-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:
+To make chat-style inserts automatically follow the latest visible edge, pass `autoFollow: true`. When the corresponding auto-follow latch is armed, the insert behaves like a conditional `jumpToTop()` / `jumpToBottom()` after the items are inserted:
 
 ```ts
 list.pushAll([nextMessage], {
-  followIfAtBoundary: true,
+  autoFollow: true,
   duration: 220,
 });
 ```

package/example/chat.ts

@@ -505,6 +505,7 @@ const renderer = new ListRenderer(ctx, {
   renderItem,
   list,
 });
+renderer.padding = { top: 32, bottom: 32 };
 let nextMessageId = list.items.length + 1;
 
 function drawFrame(): void {
@@ -513,19 +514,32 @@ function drawFrame(): void {
     maxIdx: Number.NaN,
     min: Number.NaN,
     max: Number.NaN,
+    canAutoFollowTop: false,
+    canAutoFollowBottom: false,
   };
   renderer.render(feedback);
 
   ctx.save();
+
+  ctx.fillStyle = "rgba(255, 0, 255, 0.5)";
+  ctx.fillRect(0, 0, canvas.clientWidth, 32);
+  ctx.fillRect(0, canvas.clientHeight - 32, canvas.clientWidth, 32);
+
   ctx.textBaseline = "top";
   ctx.font = "12px system-ui";
   ctx.fillStyle = "black";
   ctx.strokeStyle = "white";
   ctx.lineWidth = 4;
   ctx.lineJoin = "round";
-  const text = JSON.stringify(feedback);
-  ctx.strokeText(text, 10, 10);
-  ctx.fillText(text, 10, 10);
+  const lines = Object.entries(feedback).map(
+    ([key, value]) => `${key}: ${String(value)}`,
+  );
+  const lineHeight = 14;
+  for (const [index, line] of lines.entries()) {
+    const y = 10 + index * lineHeight;
+    ctx.strokeText(line, 10, y);
+    ctx.fillText(line, 10, y);
+  }
   ctx.restore();
 
   requestAnimationFrame(drawFrame);
@@ -644,7 +658,7 @@ button("unshift", () => {
     ],
     {
       duration: INSERT_ANIMATION_DURATION,
-      followIfAtBoundary: true,
+      autoFollow: true,
     },
   );
 });
@@ -660,8 +674,7 @@ button("push", () => {
       },
     ],
     {
-      distance: 24,
-      followIfAtBoundary: true,
+      autoFollow: true,
     },
   );
 });

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.
@@ -520,19 +524,25 @@ interface DeleteListItemAnimationOptions {
 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;
+  autoFollow?: boolean;
 }
 type PushListItemsAnimationOptions = InsertListItemsAnimationOptions;
 type UnshiftListItemsAnimationOptions = InsertListItemsAnimationOptions;
+type ListScrollMutationSource = "external" | "internal";
+type ListScrollStatePatch = {
+  position?: number | undefined;
+  offset?: number;
+};
+declare const WRITE_LIST_SCROLL_STATE: unique symbol;
 declare class ListState<T extends {}> {
   #private;
   /** Pixel offset from the anchored item edge. */
-  offset: number;
+  get offset(): number;
+  set offset(value: number);
   /** Anchor item index, or `undefined` to use the renderer default. */
-  position: number | undefined;
+  get position(): number | undefined;
+  set position(value: number | undefined);
   /** Items currently managed by the renderer. */
   get items(): T[];
   /** Replaces the full item collection while preserving scroll state. */
@@ -573,6 +583,7 @@ declare class ListState<T extends {}> {
   resetScroll(): void;
   /** Applies a relative pixel scroll delta. */
   applyScroll(delta: number): void;
+  [WRITE_LIST_SCROLL_STATE](patch: ListScrollStatePatch, source: ListScrollMutationSource): void;
 }
 //#endregion
 //#region src/renderer/memo.d.ts
@@ -593,6 +604,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;
@@ -602,13 +617,31 @@ type VirtualizedResolvedItem = {
 //#region src/renderer/virtualized/solver.d.ts
 type ListAnchorMode = "top" | "bottom";
 type ListUnderflowAlign = "top" | "bottom";
+interface ListPadding {
+  top?: number;
+  bottom?: number;
+}
+interface ResolvedListPadding {
+  top: number;
+  bottom: number;
+}
 interface ListLayoutOptions {
   anchorMode?: ListAnchorMode;
   underflowAlign?: ListUnderflowAlign;
+  padding?: ListPadding;
 }
 interface ResolvedListLayoutOptions {
   anchorMode: ListAnchorMode;
   underflowAlign: ListUnderflowAlign;
+  padding: ResolvedListPadding;
+}
+interface ListViewportMetrics {
+  outerHeight: number;
+  contentTop: number;
+  contentBottom: number;
+  contentHeight: number;
+  outerContentTop: number;
+  outerContentBottom: number;
 }
 interface VisibleListState {
   position?: number;
@@ -690,17 +723,30 @@ declare abstract class VirtualizedRenderer<C extends CanvasRenderingContext2D, T
    * 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, extraShift?: number): boolean;
+  protected _renderVisibleWindow(window: VisibleWindow<VirtualizedResolvedItem>, feedback?: RenderFeedback): boolean;
+  protected _readAutoFollowCapabilities(window: VisibleWindow<VirtualizedResolvedItem>): AutoFollowCapabilities;
   protected _readVisibleRange(top: number, height: number): {
     top: number;
     bottom: number;
   } | undefined;
+  protected _readOuterVisibleRange(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 _hittestVisibleWindow(window: VisibleWindow<VirtualizedResolvedItem>, test: HitTest): boolean;
+  protected _captureVisibleItemSnapshot(solution: VisibleWindowResult<unknown>): void;
   protected _prepareRender(now: number): boolean;
   protected _finishRender(requestRedraw: boolean): boolean;
   protected _clampItemIndex(index: number): number;
@@ -719,6 +765,7 @@ declare abstract class VirtualizedRenderer<C extends CanvasRenderingContext2D, T
   protected abstract _applyAnchor(anchor: number): void;
   protected abstract _getDefaultJumpBlock(): NonNullable<JumpToOptions["block"]>;
   protected abstract _getTargetAnchor(index: number, block: NonNullable<JumpToOptions["block"]>): number;
+  protected _getViewportMetrics(): ListViewportMetrics;
 }
 //#endregion
 //#region src/renderer/virtualized/list.d.ts
@@ -732,6 +779,8 @@ interface ListRendererOptions<C extends CanvasRenderingContext2D, T extends {}>
 declare class ListRenderer<C extends CanvasRenderingContext2D, T extends {}> extends VirtualizedRenderer<C, T> {
   #private;
   constructor(graphics: C, options: ListRendererOptions<C, T>);
+  get padding(): ListPadding;
+  set padding(value: ListPadding);
   protected _getLayoutOptions(): ResolvedListLayoutOptions;
   protected _resolveVisibleWindowForState(state: VisibleListState, now: number): VisibleWindowResult<VirtualizedResolvedItem>;
   protected _getDefaultJumpBlock(): NonNullable<JumpToOptions["block"]>;
@@ -741,5 +790,5 @@ declare class ListRenderer<C extends CanvasRenderingContext2D, T extends {}> ext
   protected _getTargetAnchor(index: number, block: NonNullable<JumpToOptions["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, 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, 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 };
 //# sourceMappingURL=index.d.mts.map