chat-layout 1.2.0-6 → 1.2.0-8

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,
 });
 ```
@@ -178,7 +178,7 @@ Notes:
 - `FlexItem` exposes `grow`, `shrink`, and `alignSelf`; `basis` is no longer public.
 - `MultilineText` now uses `align` / `physicalAlign` instead of `alignment`.
 - `ListState.position` uses `undefined` for the renderer default anchor.
-- Use `list.resetScroll()` or `list.setAnchor(index, offset)` instead of assigning `Number.NaN`.
+- Use `list.applyScroll(delta)` for relative scrolling, or renderer `jumpTo()` / `jumpToTop()` / `jumpToBottom()` for absolute navigation.
 
 ## Development
 

package/example/chat.ts

@@ -1,7 +1,7 @@
 import {
+  Fixed,
   Flex,
   FlexItem,
-  Fixed,
   ListRenderer,
   ListState,
   MultilineText,
@@ -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 {
@@ -519,15 +520,26 @@ function drawFrame(): void {
   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);
@@ -662,7 +674,6 @@ button("push", () => {
       },
     ],
     {
-      distance: 24,
       autoFollow: true,
     },
   );

package/index.d.mts

@@ -524,19 +524,24 @@ 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. */
   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 const FINALIZE_LIST_DELETE: unique symbol;
 declare class ListState<T extends {}> {
   #private;
   /** Pixel offset from the anchored item edge. */
-  offset: number;
+  get offset(): number;
   /** Anchor item index, or `undefined` to use the renderer default. */
-  position: number | undefined;
+  get position(): number | undefined;
   /** Items currently managed by the renderer. */
   get items(): T[];
   /** Replaces the full item collection while preserving scroll state. */
@@ -564,19 +569,14 @@ declare class ListState<T extends {}> {
   /**
    * Finalizes a pending delete by removing the item from the list.
    */
-  finalizeDelete(item: T): void;
-  /**
-   * Sets the current anchor item and pixel offset.
-   */
-  setAnchor(position: number, offset?: number): void;
+  [FINALIZE_LIST_DELETE](item: T): void;
   /**
    * Replaces all items and clears scroll state.
    */
   reset(items?: T[]): void;
-  /** Clears the current scroll anchor while keeping the items. */
-  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
@@ -596,27 +596,34 @@ declare function memoRenderItemBy<C extends CanvasRenderingContext2D, T, K>(keyO
   resetKey: (key: K) => boolean;
 };
 //#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;
-  hittest: (test: HitTest, y: number) => boolean;
-};
-//#endregion
 //#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;
@@ -627,7 +634,7 @@ interface NormalizedListState {
   offset: number;
 }
 interface VisibleWindowEntry<T> {
-  idx: number;
+  index: number;
   value: T;
   offset: number;
   height: number;
@@ -642,6 +649,17 @@ interface VisibleWindowResult<T> {
   window: VisibleWindow<T>;
 }
 //#endregion
+//#region src/renderer/virtualized/virtualized-types.d.ts
+type AutoFollowCapabilities = {
+  top: boolean;
+  bottom: boolean;
+};
+/** 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/base.d.ts
 /**
  * Options for programmatic scrolling to a target item.
@@ -673,12 +691,8 @@ declare abstract class VirtualizedRenderer<C extends CanvasRenderingContext2D, T
   });
   /** Current anchor item index. */
   get position(): number | undefined;
-  /** Updates the current anchor item index. */
-  set position(value: number | undefined);
   /** Pixel offset from the anchored item edge. */
   get offset(): number;
-  /** Updates the pixel offset from the anchored item edge. */
-  set offset(value: number);
   /** Items currently available to the renderer. */
   get items(): T[];
   /** Replaces the current item collection. */
@@ -709,15 +723,19 @@ declare abstract class VirtualizedRenderer<C extends CanvasRenderingContext2D, T
   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 _readAutoFollowCapabilities(window: VisibleWindow<VirtualizedResolvedItem>, extraShift?: number): AutoFollowCapabilities;
+  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;
@@ -736,6 +754,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
@@ -749,6 +768,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"]>;
@@ -758,5 +779,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