chat-layout 1.0.0-3 → 1.0.0-4

package/index.d.mts

@@ -1,6 +1,15 @@
 //#region src/types.d.ts
+/**
+ * A value that can be provided directly or derived lazily from the active canvas context.
+ */
 type DynValue<C extends CanvasRenderingContext2D, T> = T extends Function ? never : T | ((context: C) => T);
+/**
+ * Base renderer configuration.
+ */
 interface RendererOptions {}
+/**
+ * Describes which items are currently visible after a render pass.
+ */
 interface RenderFeedback {
   /** Smallest visible item index that contributes a positive visible height. */
   minIdx: number;
@@ -11,65 +20,136 @@ interface RenderFeedback {
   /** Largest visible continuous item position, expressed in item coordinates rather than pixels. */
   max: number;
 }
+/**
+ * The main axis direction used by flex containers.
+ */
 type Axis = "row" | "column";
+/**
+ * Distribution modes for free space along the main axis.
+ */
 type MainAxisAlignment = "start" | "center" | "end" | "space-between" | "space-around" | "space-evenly";
+/**
+ * Alignment modes along the cross axis.
+ */
 type CrossAxisAlignment = "start" | "center" | "end" | "stretch";
+/**
+ * Controls whether a flex container fills the available main-axis size or shrink-wraps its content.
+ */
 type MainAxisSize = "fill" | "fit-content";
+/**
+ * Logical inline alignment.
+ */
 type TextAlign = "start" | "center" | "end";
+/**
+ * Physical inline alignment.
+ */
 type PhysicalTextAlign = "left" | "center" | "right";
+/**
+ * Whitespace normalization mode for text measurement and layout.
+ */
 type TextWhitespaceMode = "preserve" | "trim-and-collapse";
+/**
+ * Shared text styling options for text nodes.
+ */
 interface TextStyleOptions<C extends CanvasRenderingContext2D> {
+  /** Height of each rendered line in CSS pixels. */
   lineHeight: number;
+  /** Canvas font string used for measurement and drawing. */
   font: string;
+  /** Fill style or resolver used when drawing the text. */
   style: DynValue<C, string>;
   /** Default: preserve input whitespace, including blank lines and edge spaces. */
   whitespace?: TextWhitespaceMode;
 }
+/**
+ * Options for multi-line text nodes.
+ */
 interface MultilineTextOptions<C extends CanvasRenderingContext2D> extends TextStyleOptions<C> {
   /** Logical alignment that matches `Place.align`. */
   align?: TextAlign;
   /** Explicit physical alignment when left/right semantics are required. */
   physicalAlign?: PhysicalTextAlign;
 }
+/**
+ * Options for single-line text nodes.
+ */
 interface TextOptions<C extends CanvasRenderingContext2D> extends TextStyleOptions<C> {}
+/**
+ * Optional layout bounds passed down during measurement and drawing.
+ */
 interface LayoutConstraints {
+  /** Minimum width the node should occupy. */
   minWidth?: number;
+  /** Maximum width the node may occupy. */
   maxWidth?: number;
+  /** Minimum height the node should occupy. */
   minHeight?: number;
+  /** Maximum height the node may occupy. */
   maxHeight?: number;
 }
+/**
+ * Per-child flex behavior overrides.
+ */
 interface FlexItemOptions {
+  /** Share of positive free space assigned to this item. */
   grow?: number;
   /** Compatibility-first default: 0 (opt-in shrink). */
   shrink?: number;
+  /** Cross-axis alignment override for this item. */
   alignSelf?: CrossAxisAlignment | "auto";
 }
+/**
+ * Configuration for a flex container node.
+ */
 interface FlexContainerOptions {
+  /** Main axis direction. Defaults to `"row"`. */
   direction?: Axis;
+  /** Gap inserted between adjacent items. */
   gap?: number;
+  /** Main-axis distribution of free space. */
   justifyContent?: MainAxisAlignment;
+  /** Default cross-axis alignment for children. */
   alignItems?: CrossAxisAlignment;
+  /** Whether children should be laid out in reverse order. */
   reverse?: boolean;
+  /** Whether the container fills or shrink-wraps the main axis. */
   mainAxisSize?: MainAxisSize;
 }
+/**
+ * Runtime services exposed to every node during layout, drawing, and hit-testing.
+ */
 interface Context<C extends CanvasRenderingContext2D> {
+  /** The backing canvas rendering context. */
   graphics: C;
-  /** v2: 显式布局约束 */
+  /** Active layout constraints for the current call stack. */
   constraints?: LayoutConstraints;
+  /** Measures another node under optional constraints. */
   measureNode(node: Node<C>, constraints?: LayoutConstraints): Box;
+  /** Invalidates cached measurements for a node and its ancestors. */
   invalidateNode(node: Node<C>): void;
+  /** Resolves a dynamic value against the current graphics context. */
   resolveDynValue<T>(value: DynValue<C, T>): T;
+  /** Saves the canvas state for the callback and restores it afterwards. */
   with<T>(this: Context<C>, cb: (g: C) => T): T;
 }
+/**
+ * Width and height pair in CSS pixels.
+ */
 interface Box {
   width: number;
   height: number;
 }
+/**
+ * Pointer test input routed through the node tree.
+ */
 interface HitTest {
   x: number;
   y: number;
   type: "click" | "auxclick" | "hover";
 }
+/**
+ * Fundamental layout node contract.
+ */
 interface Node<C extends CanvasRenderingContext2D> {
   /** Measure the node under the current layout constraints. */
   measure(ctx: Context<C>): Box;
@@ -78,18 +158,27 @@ interface Node<C extends CanvasRenderingContext2D> {
   draw(ctx: Context<C>, x: number, y: number): boolean;
   hittest(ctx: Context<C>, test: HitTest): boolean;
 }
+/**
+ * Rectangular region in local coordinates.
+ */
 interface LayoutRect {
   x: number;
   y: number;
   width: number;
   height: number;
 }
+/**
+ * Stored layout data for a single child node.
+ */
 interface ChildLayoutResult<C extends CanvasRenderingContext2D> {
   node: Node<C>;
   rect: LayoutRect;
   contentBox: LayoutRect;
   constraints?: LayoutConstraints;
 }
+/**
+ * Cached layout data for a container and its children.
+ */
 interface FlexLayoutResult<C extends CanvasRenderingContext2D> {
   containerBox: LayoutRect;
   contentBox: LayoutRect;
@@ -98,19 +187,37 @@ interface FlexLayoutResult<C extends CanvasRenderingContext2D> {
 }
 //#endregion
 //#region src/nodes/base.d.ts
+/**
+ * A node that owns an ordered list of child nodes.
+ */
 declare abstract class Group<C extends CanvasRenderingContext2D> implements Node<C> {
   #private;
+  /**
+   * @param children Initial child nodes, in layout order.
+   */
   constructor(children: Node<C>[]);
+  /** Child nodes managed by this group. */
   get children(): readonly Node<C>[];
+  /**
+   * Replaces the full child list while updating parent links.
+   */
   replaceChildren(nextChildren: Node<C>[]): void;
   abstract measure(ctx: Context<C>): Box;
   abstract draw(ctx: Context<C>, x: number, y: number): boolean;
   abstract hittest(ctx: Context<C>, test: HitTest): boolean;
 }
+/**
+ * A node that forwards layout and drawing to a single inner node.
+ */
 declare class Wrapper<C extends CanvasRenderingContext2D> implements Node<C> {
   #private;
+  /**
+   * @param inner Wrapped child node.
+   */
   constructor(inner: Node<C>);
+  /** The wrapped child node. */
   get inner(): Node<C>;
+  /** Replaces the wrapped child node. */
   set inner(newNode: Node<C>);
   measure(ctx: Context<C>): Box;
   measureMinContent(ctx: Context<C>): Box;
@@ -119,6 +226,9 @@ declare class Wrapper<C extends CanvasRenderingContext2D> implements Node<C> {
 }
 //#endregion
 //#region src/nodes/box.d.ts
+/**
+ * Adds padding around a single child node.
+ */
 declare class PaddingBox<C extends CanvasRenderingContext2D> extends Wrapper<C> {
   #private;
   readonly padding: {
@@ -127,6 +237,10 @@ declare class PaddingBox<C extends CanvasRenderingContext2D> extends Wrapper<C>
     left?: number;
     right?: number;
   };
+  /**
+   * @param inner Wrapped child node.
+   * @param padding Padding in CSS pixels on each side.
+   */
   constructor(inner: Node<C>, padding?: {
     top?: number;
     bottom?: number;
@@ -138,9 +252,16 @@ declare class PaddingBox<C extends CanvasRenderingContext2D> extends Wrapper<C>
   draw(ctx: Context<C>, x: number, y: number): boolean;
   hittest(ctx: Context<C>, test: HitTest): boolean;
 }
+/**
+ * A leaf node with a fixed size and no drawing behavior.
+ */
 declare class Fixed<C extends CanvasRenderingContext2D> implements Node<C> {
   readonly width: number;
   readonly height: number;
+  /**
+   * @param width Fixed width in CSS pixels.
+   * @param height Fixed height in CSS pixels.
+   */
   constructor(width: number, height: number);
   measure(_ctx: Context<C>): Box;
   measureMinContent(_ctx: Context<C>): Box;
@@ -149,12 +270,26 @@ declare class Fixed<C extends CanvasRenderingContext2D> implements Node<C> {
 }
 //#endregion
 //#region src/nodes/flex.d.ts
+/**
+ * Wraps a child node with per-item flex options.
+ */
 declare class FlexItem<C extends CanvasRenderingContext2D> extends Wrapper<C> {
   readonly item: FlexItemOptions;
+  /**
+   * @param inner Wrapped child node.
+   * @param item Flex behavior overrides for the child.
+   */
   constructor(inner: Node<C>, item?: FlexItemOptions);
 }
+/**
+ * Lays out children in a single flex row or column.
+ */
 declare class Flex<C extends CanvasRenderingContext2D> extends Group<C> {
   readonly options: FlexContainerOptions;
+  /**
+   * @param children Child nodes in visual order.
+   * @param options Flex container configuration.
+   */
   constructor(children: Node<C>[], options?: FlexContainerOptions);
   measure(ctx: Context<C>): Box;
   measureMinContent(ctx: Context<C>): Box;
@@ -163,11 +298,18 @@ declare class Flex<C extends CanvasRenderingContext2D> extends Group<C> {
 }
 //#endregion
 //#region src/nodes/place.d.ts
+/**
+ * Aligns a single child horizontally within the available width.
+ */
 declare class Place<C extends CanvasRenderingContext2D> extends Wrapper<C> {
   readonly options: {
     align?: TextAlign;
     expand?: boolean;
   };
+  /**
+   * @param inner Wrapped child node.
+   * @param options Alignment behavior for the child.
+   */
   constructor(inner: Node<C>, options?: {
     align?: TextAlign;
     expand?: boolean;
@@ -179,9 +321,16 @@ declare class Place<C extends CanvasRenderingContext2D> extends Wrapper<C> {
 }
 //#endregion
 //#region src/nodes/text.d.ts
+/**
+ * Draws wrapped text using the configured line height and alignment.
+ */
 declare class MultilineText<C extends CanvasRenderingContext2D> implements Node<C> {
   readonly text: string;
   readonly options: MultilineTextOptions<C>;
+  /**
+   * @param text Source text to measure and draw.
+   * @param options Text layout and drawing options.
+   */
   constructor(text: string, options: MultilineTextOptions<C>);
   measure(ctx: Context<C>): Box;
   measureMinContent(ctx: Context<C>): Box;
@@ -192,9 +341,16 @@ declare class MultilineText<C extends CanvasRenderingContext2D> implements Node<
     type: "click" | "auxclick" | "hover";
   }): boolean;
 }
+/**
+ * Draws a single line of text, clipped logically by measurement width.
+ */
 declare class Text<C extends CanvasRenderingContext2D> implements Node<C> {
   readonly text: string;
   readonly options: TextOptions<C>;
+  /**
+   * @param text Source text to measure and draw.
+   * @param options Text layout and drawing options.
+   */
   constructor(text: string, options: TextOptions<C>);
   measure(ctx: Context<C>): Box;
   measureMinContent(ctx: Context<C>): Box;
@@ -207,49 +363,105 @@ declare class Text<C extends CanvasRenderingContext2D> implements Node<C> {
 }
 //#endregion
 //#region src/renderer/base.d.ts
+/**
+ * Base renderer that provides measurement, layout caching, and drawing helpers.
+ */
 declare class BaseRenderer<C extends CanvasRenderingContext2D, O extends {} = {}> {
   #private;
   readonly options: RendererOptions & O;
+  /** Canvas rendering context used by this renderer. */
   graphics: C;
   protected get context(): Context<C>;
+  /**
+   * @param graphics Canvas rendering context used for all layout and drawing.
+   * @param options Renderer-specific options.
+   */
   constructor(graphics: C, options: RendererOptions & O);
   protected getRootConstraints(): LayoutConstraints;
   protected getRootContext(): Context<C>;
   protected measureRootNode(node: Node<C>): Box;
   protected drawRootNode(node: Node<C>, x?: number, y?: number): boolean;
   protected hittestRootNode(node: Node<C>, test: HitTest): boolean;
+  /**
+   * Drops cached measurements for a node and every ancestor that depends on it.
+   */
   invalidateNode(node: Node<C>): void;
+  /**
+   * Returns the cached layout result for a node under the given constraints, if available.
+   */
   getLayoutResult(node: Node<C>, constraints?: LayoutConstraints): FlexLayoutResult<C> | undefined;
+  /**
+   * Stores a layout result for later draw and hit-test passes.
+   */
   setLayoutResult(node: Node<C>, result: FlexLayoutResult<C>, constraints?: LayoutConstraints): void;
   protected getTextLayout<T>(node: Node<C>, key: string): T | undefined;
   protected setTextLayout<T>(node: Node<C>, key: string, layout: T): void;
+  /**
+   * Measures a node under optional constraints, using cached results when possible.
+   */
   measureNode(node: Node<C>, constraints?: LayoutConstraints): Box;
 }
+/**
+ * Immediate-mode renderer for a single root node.
+ */
 declare class DebugRenderer<C extends CanvasRenderingContext2D> extends BaseRenderer<C> {
+  /**
+   * Clears the viewport and draws the provided root node.
+   */
   draw(node: Node<C>): boolean;
+  /**
+   * Hit-tests the provided root node using viewport-relative coordinates.
+   */
   hittest(node: Node<C>, test: HitTest): boolean;
 }
 //#endregion
 //#region src/renderer/list-state.d.ts
+/**
+ * Mutable list state shared with virtualized renderers.
+ */
 declare class ListState<T extends {}> {
+  /** Pixel offset from the anchored item edge. */
   offset: number;
+  /** Anchor item index, or `undefined` to use the renderer default. */
   position: number | undefined;
+  /** Items currently managed by the renderer. */
   items: T[];
+  /**
+   * @param items Initial list items.
+   */
   constructor(items?: T[]);
+  /** Prepends one or more items. */
   unshift(...items: T[]): void;
+  /** Prepends an array of items. */
   unshiftAll(items: T[]): void;
+  /** Appends one or more items. */
   push(...items: T[]): void;
+  /** Appends an array of items. */
   pushAll(items: T[]): void;
+  /**
+   * Sets the current anchor item and pixel offset.
+   */
   setAnchor(position: number, offset?: number): 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;
 }
 //#endregion
 //#region src/renderer/memo.d.ts
+/**
+ * Memoizes `renderItem` by object identity.
+ */
 declare function memoRenderItem<C extends CanvasRenderingContext2D, T extends object>(renderItem: (item: T) => Node<C>): ((item: T) => Node<C>) & {
   reset: (key: T) => boolean;
 };
+/**
+ * Memoizes `renderItem` by a caller-provided cache key.
+ */
 declare function memoRenderItemBy<C extends CanvasRenderingContext2D, T, K>(keyOf: (item: T) => K, renderItem: (item: T) => Node<C>): ((item: T) => Node<C>) & {
   reset: (item: T) => boolean;
   resetKey: (key: K) => boolean;
@@ -276,12 +488,22 @@ interface VisibleWindow<T> {
 }
 //#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.
+ */
 declare abstract class VirtualizedRenderer<C extends CanvasRenderingContext2D, T extends {}> extends BaseRenderer<C, {
   renderItem: (item: T) => Node<C>;
   list: ListState<T>;
@@ -290,13 +512,21 @@ declare abstract class VirtualizedRenderer<C extends CanvasRenderingContext2D, T
   static readonly MIN_JUMP_DURATION = 160;
   static readonly MAX_JUMP_DURATION = 420;
   static readonly JUMP_DURATION_PER_ITEM = 28;
+  /** 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. */
   set items(value: T[]);
+  /** Renders the current visible window. */
   abstract render(feedback?: RenderFeedback): boolean;
+  /** Hit-tests the current visible window. */
   abstract hittest(test: {
     x: number;
     y: number;
@@ -304,6 +534,9 @@ declare abstract class VirtualizedRenderer<C extends CanvasRenderingContext2D, T
   }): boolean;
   protected _readListState(): VisibleListState;
   protected _commitListState(state: NormalizedListState): void;
+  /**
+   * Scrolls the viewport to the requested item index.
+   */
   jumpTo(index: number, options?: JumpToOptions): void;
   protected _resetRenderFeedback(feedback?: RenderFeedback): void;
   protected _accumulateRenderFeedback(feedback: RenderFeedback, idx: number, top: number, height: number): void;
@@ -327,6 +560,9 @@ declare abstract class VirtualizedRenderer<C extends CanvasRenderingContext2D, T
 }
 //#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"]>;
@@ -339,6 +575,9 @@ declare class ChatRenderer<C extends CanvasRenderingContext2D, T extends {}> ext
 }
 //#endregion
 //#region src/renderer/virtualized/timeline.d.ts
+/**
+ * Virtualized renderer anchored to the top, suitable for timeline-style UIs.
+ */
 declare class TimelineRenderer<C extends CanvasRenderingContext2D, T extends {}> extends VirtualizedRenderer<C, T> {
   #private;
   protected _getDefaultJumpBlock(): NonNullable<JumpToOptions["block"]>;