chat-layout 1.0.0-2 → 1.0.0-4

package/index.mjs

@@ -74,30 +74,48 @@ function measureNodeMinContent(ctx, node, constraints = ctx.constraints) {
 	if (node.measureMinContent != null) return node.measureMinContent(nextCtx);
 	return node.measure(nextCtx);
 }
+/**
+* A node that owns an ordered list of child nodes.
+*/
 var Group = class {
 	#children;
+	/**
+	* @param children Initial child nodes, in layout order.
+	*/
 	constructor(children) {
 		this.#children = [...children];
 		replaceNodesParent([], this.#children, this);
 	}
+	/** Child nodes managed by this group. */
 	get children() {
 		return this.#children;
 	}
+	/**
+	* Replaces the full child list while updating parent links.
+	*/
 	replaceChildren(nextChildren) {
 		const nextSnapshot = [...nextChildren];
 		replaceNodesParent(this.#children, nextSnapshot, this);
 		this.#children = nextSnapshot;
 	}
 };
+/**
+* A node that forwards layout and drawing to a single inner node.
+*/
 var Wrapper = class {
 	#inner;
+	/**
+	* @param inner Wrapped child node.
+	*/
 	constructor(inner) {
 		this.#inner = inner;
 		attachNodeToParent(this.#inner, this);
 	}
+	/** The wrapped child node. */
 	get inner() {
 		return this.#inner;
 	}
+	/** Replaces the wrapped child node. */
 	set inner(newNode) {
 		if (newNode === this.#inner) return;
 		replaceNodeParent(this.#inner, newNode, this);
@@ -227,7 +245,14 @@ function shrinkConstraint(value, padding) {
 	if (value == null) return;
 	return Math.max(0, value - padding);
 }
+/**
+* Adds padding around a single child node.
+*/
 var PaddingBox = class extends Wrapper {
+	/**
+	* @param inner Wrapped child node.
+	* @param padding Padding in CSS pixels on each side.
+	*/
 	constructor(inner, padding = {}) {
 		super(inner);
 		this.padding = padding;
@@ -315,7 +340,14 @@ var PaddingBox = class extends Wrapper {
 		}));
 	}
 };
+/**
+* A leaf node with a fixed size and no drawing behavior.
+*/
 var Fixed = class {
+	/**
+	* @param width Fixed width in CSS pixels.
+	* @param height Fixed height in CSS pixels.
+	*/
 	constructor(width, height) {
 		this.width = width;
 		this.height = height;
@@ -652,13 +684,27 @@ function computeFlexLayout(children, options, constraints, measureChild, measure
 		}
 	};
 }
+/**
+* Wraps a child node with per-item flex options.
+*/
 var FlexItem = class extends Wrapper {
+	/**
+	* @param inner Wrapped child node.
+	* @param item Flex behavior overrides for the child.
+	*/
 	constructor(inner, item = {}) {
 		super(inner);
 		this.item = item;
 	}
 };
+/**
+* Lays out children in a single flex row or column.
+*/
 var Flex = class extends Group {
+	/**
+	* @param children Child nodes in visual order.
+	* @param options Flex container configuration.
+	*/
 	constructor(children, options = {}) {
 		super(children);
 		this.options = options;
@@ -713,7 +759,14 @@ function resolveHorizontalOffset(align, availableWidth, childWidth) {
 		case "start": return 0;
 	}
 }
+/**
+* Aligns a single child horizontally within the available width.
+*/
 var Place = class extends Wrapper {
+	/**
+	* @param inner Wrapped child node.
+	* @param options Alignment behavior for the child.
+	*/
 	constructor(inner, options = {}) {
 		super(inner);
 		this.options = options;
@@ -1048,7 +1101,14 @@ function getSingleLineMinContentLayout(node, ctx, text, whitespace) {
 function getMultiLineMinContentLayout(node, ctx, text, whitespace) {
 	return readCachedTextLayout(node, ctx, getMultiLineMinContentLayoutKey(), () => measureTextMinContent(ctx, text, whitespace));
 }
+/**
+* Draws wrapped text using the configured line height and alignment.
+*/
 var MultilineText = class {
+	/**
+	* @param text Source text to measure and draw.
+	* @param options Text layout and drawing options.
+	*/
 	constructor(text, options) {
 		this.text = text;
 		this.options = options;
@@ -1109,7 +1169,14 @@ var MultilineText = class {
 		return false;
 	}
 };
+/**
+* Draws a single line of text, clipped logically by measurement width.
+*/
 var Text = class {
+	/**
+	* @param text Source text to measure and draw.
+	* @param options Text layout and drawing options.
+	*/
 	constructor(text, options) {
 		this.text = text;
 		this.options = options;
@@ -1154,7 +1221,11 @@ function constraintKey(constraints) {
 	if (constraints == null) return "";
 	return `${constraints.minWidth ?? ""},${constraints.maxWidth ?? ""},${constraints.minHeight ?? ""},${constraints.maxHeight ?? ""}`;
 }
+/**
+* Base renderer that provides measurement, layout caching, and drawing helpers.
+*/
 var BaseRenderer = class {
+	/** Canvas rendering context used by this renderer. */
 	graphics;
 	#ctx;
 	#lastWidth;
@@ -1164,6 +1235,10 @@ var BaseRenderer = class {
 	get context() {
 		return shallow(this.#ctx);
 	}
+	/**
+	* @param graphics Canvas rendering context used for all layout and drawing.
+	* @param options Renderer-specific options.
+	*/
 	constructor(graphics, options) {
 		this.options = options;
 		this.graphics = graphics;
@@ -1232,6 +1307,9 @@ var BaseRenderer = class {
 		this.measureRootNode(node);
 		return node.hittest(this.getRootContext(), test);
 	}
+	/**
+	* Drops cached measurements for a node and every ancestor that depends on it.
+	*/
 	invalidateNode(node) {
 		this.#syncCachesToViewportWidth();
 		this.#cache.delete(node);
@@ -1243,6 +1321,9 @@ var BaseRenderer = class {
 			this.#textLayoutCache.delete(ancestor);
 		});
 	}
+	/**
+	* Returns the cached layout result for a node under the given constraints, if available.
+	*/
 	getLayoutResult(node, constraints) {
 		this.#syncCachesToViewportWidth();
 		const nodeCache = this.#layoutCache.get(node);
@@ -1256,6 +1337,9 @@ var BaseRenderer = class {
 		}
 		return cached.layout;
 	}
+	/**
+	* Stores a layout result for later draw and hit-test passes.
+	*/
 	setLayoutResult(node, result, constraints) {
 		this.#syncCachesToViewportWidth();
 		let nodeCache = this.#layoutCache.get(node);
@@ -1298,6 +1382,9 @@ var BaseRenderer = class {
 			layout
 		});
 	}
+	/**
+	* Measures a node under optional constraints, using cached results when possible.
+	*/
 	measureNode(node, constraints) {
 		this.#syncCachesToViewportWidth();
 		{
@@ -1330,51 +1417,81 @@ var BaseRenderer = class {
 		return result;
 	}
 };
+/**
+* Immediate-mode renderer for a single root node.
+*/
 var DebugRenderer = class extends BaseRenderer {
+	/**
+	* Clears the viewport and draws the provided root node.
+	*/
 	draw(node) {
 		const { clientWidth: viewportWidth, clientHeight: viewportHeight } = this.graphics.canvas;
 		this.graphics.clearRect(0, 0, viewportWidth, viewportHeight);
 		return this.drawRootNode(node);
 	}
+	/**
+	* Hit-tests the provided root node using viewport-relative coordinates.
+	*/
 	hittest(node, test) {
 		return this.hittestRootNode(node, test);
 	}
 };
 //#endregion
 //#region src/renderer/list-state.ts
+/**
+* Mutable list state shared with virtualized renderers.
+*/
 var ListState = class {
+	/** Pixel offset from the anchored item edge. */
 	offset = 0;
+	/** Anchor item index, or `undefined` to use the renderer default. */
 	position;
+	/** Items currently managed by the renderer. */
 	items = [];
+	/**
+	* @param items Initial list items.
+	*/
 	constructor(items = []) {
 		this.items = [...items];
 	}
+	/** Prepends one or more items. */
 	unshift(...items) {
 		this.unshiftAll(items);
 	}
+	/** Prepends an array of items. */
 	unshiftAll(items) {
 		if (this.position != null) this.position += items.length;
 		this.items = items.concat(this.items);
 	}
+	/** Appends one or more items. */
 	push(...items) {
 		this.pushAll(items);
 	}
+	/** Appends an array of items. */
 	pushAll(items) {
 		this.items.push(...items);
 	}
+	/**
+	* Sets the current anchor item and pixel offset.
+	*/
 	setAnchor(position, offset = 0) {
 		this.position = Number.isFinite(position) ? Math.trunc(position) : void 0;
 		this.offset = Number.isFinite(offset) ? offset : 0;
 	}
+	/**
+	* Replaces all items and clears scroll state.
+	*/
 	reset(items = []) {
 		this.items = [...items];
 		this.offset = 0;
 		this.position = void 0;
 	}
+	/** Clears the current scroll anchor while keeping the items. */
 	resetScroll() {
 		this.offset = 0;
 		this.position = void 0;
 	}
+	/** Applies a relative pixel scroll delta. */
 	applyScroll(delta) {
 		this.offset += delta;
 	}
@@ -1384,6 +1501,9 @@ var ListState = class {
 function isWeakMapKey(value) {
 	return typeof value === "object" && value !== null || typeof value === "function";
 }
+/**
+* Memoizes `renderItem` by object identity.
+*/
 function memoRenderItem(renderItem) {
 	const cache = /* @__PURE__ */ new WeakMap();
 	function fn(item) {
@@ -1397,6 +1517,9 @@ function memoRenderItem(renderItem) {
 	}
 	return Object.assign(fn, { reset: (key) => cache.delete(key) });
 }
+/**
+* Memoizes `renderItem` by a caller-provided cache key.
+*/
 function memoRenderItemBy(keyOf, renderItem) {
 	const cache = /* @__PURE__ */ new Map();
 	function fn(item) {
@@ -1426,27 +1549,36 @@ function smoothstep(value) {
 function getNow() {
 	return globalThis.performance?.now() ?? Date.now();
 }
+/**
+* Shared base class for virtualized list renderers.
+*/
 var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 	static MIN_JUMP_DURATION = 160;
 	static MAX_JUMP_DURATION = 420;
 	static JUMP_DURATION_PER_ITEM = 28;
 	#controlledState;
 	#jumpAnimation;
+	/** Current anchor item index. */
 	get position() {
 		return this.options.list.position;
 	}
+	/** Updates the current anchor item index. */
 	set position(value) {
 		this.options.list.position = value;
 	}
+	/** Pixel offset from the anchored item edge. */
 	get offset() {
 		return this.options.list.offset;
 	}
+	/** Updates the pixel offset from the anchored item edge. */
 	set offset(value) {
 		this.options.list.offset = value;
 	}
+	/** Items currently available to the renderer. */
 	get items() {
 		return this.options.list.items;
 	}
+	/** Replaces the current item collection. */
 	set items(value) {
 		this.options.list.items = value;
 	}
@@ -1460,6 +1592,9 @@ var VirtualizedRenderer = class VirtualizedRenderer extends BaseRenderer {
 		this.position = state.position;
 		this.offset = state.offset;
 	}
+	/**
+	* Scrolls the viewport to the requested item index.
+	*/
 	jumpTo(index, options = {}) {
 		if (this.items.length === 0) {
 			this.#cancelJumpAnimation();
@@ -1795,6 +1930,9 @@ function resolveChatVisibleWindow(items, state, viewportHeight, resolveItem) {
 function clamp$1(value, min, max) {
 	return Math.min(Math.max(value, min), max);
 }
+/**
+* Virtualized renderer anchored to the bottom, suitable for chat-style UIs.
+*/
 var ChatRenderer = class extends VirtualizedRenderer {
 	#resolveVisibleWindow() {
 		return resolveChatVisibleWindow(this.items, this._readListState(), this.graphics.canvas.clientHeight, (item) => {
@@ -1854,6 +1992,9 @@ var ChatRenderer = class extends VirtualizedRenderer {
 function clamp(value, min, max) {
 	return Math.min(Math.max(value, min), max);
 }
+/**
+* Virtualized renderer anchored to the top, suitable for timeline-style UIs.
+*/
 var TimelineRenderer = class extends VirtualizedRenderer {
 	#resolveVisibleWindow() {
 		return resolveTimelineVisibleWindow(this.items, this._readListState(), this.graphics.canvas.clientHeight, (item) => {