chat-layout 1.1.2 → 1.2.0-1

package/README.md

@@ -7,13 +7,14 @@ The current v2-style APIs are:
 - `Flex`: row/column layout
 - `FlexItem`: explicit `grow` / `shrink` / `alignSelf`
 - `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
 - `memoRenderItem` / `memoRenderItemBy`: item render memoization
 
 ## Quick example
 
-Use `Flex` to build structure, `FlexItem` to control resize behavior, and `Place` to align the final bubble:
+Use `Flex` to build structure, `FlexItem` to control resize behavior, `ShrinkWrap` to keep the bubble as narrow as possible without adding lines, and `Place` to align the final bubble:
 
 ```ts
 const bubble = new RoundedBox(
@@ -26,17 +27,27 @@ const bubble = new RoundedBox(
   { top: 6, bottom: 6, left: 10, right: 10, radii: 8, fill: "#ccc" },
 );
 
+const body = new ShrinkWrap(
+  new Flex(
+    [senderLine, bubble],
+    { direction: "column", gap: 4, alignItems: item.sender === "A" ? "end" : "start" },
+  ),
+);
+
 const row = new Flex(
   [
     avatar,
-    new FlexItem(bubble, { grow: 1, shrink: 1 }),
+    new FlexItem(
+      new Place(body, {
+        align: item.sender === "A" ? "end" : "start",
+      }),
+      { grow: 1, shrink: 1 },
+    ),
   ],
   { direction: "row", gap: 4, reverse: item.sender === "A" },
 );
 
-return new Place(row, {
-  align: item.sender === "A" ? "end" : "start",
-});
+return row;
 ```
 
 See [example/chat.ts](./example/chat.ts) for a full chat example.
@@ -47,9 +58,10 @@ See [example/chat.ts](./example/chat.ts) for a full chat example.
 - `maxWidth` / `maxHeight` limit measurement, but do not automatically make children fill the cross axis.
 - Use `alignItems: "stretch"` or `alignSelf: "stretch"` when a child should fill the computed cross size.
 - `Place` is the simplest way to align a single bubble left, center, or right.
+- `ShrinkWrap` is useful when a bubble sits inside a growable slot but should still collapse to the narrowest width that preserves its current line count.
 - `MultilineText.align` uses logical values: `start`, `center`, `end`.
 - `MultilineText.physicalAlign` uses physical values: `left`, `center`, `right`.
-- `Text` and `MultilineText` default to `whiteSpace: "normal"`, matching pretext and CSS-style collapsible whitespace.
+- `Text` and `MultilineText` default to `whiteSpace: "normal"`, using the library's canvas-first collapsible whitespace behavior.
 - Use `whiteSpace: "pre-wrap"` when blank lines, hard breaks, or edge spaces must stay visible.
 - `Text` and `MultilineText` default to `overflowWrap: "break-word"`, which preserves compatibility-first min-content sizing for shrink layouts.
 - Use `overflowWrap: "anywhere"` when long unspaced strings should contribute grapheme-level breakpoints to min-content sizing.
@@ -103,6 +115,7 @@ Notes:
 - Shrink only applies when there is a finite main-axis constraint and total content size overflows it.
 - Overflow is redistributed by `shrink * basis`; today `basis` is internal-only and always `"auto"`.
 - Custom nodes can implement `measureMinContent()` for better shrink results.
+- `ShrinkWrap` complements flex shrink: it keeps probing narrower `maxWidth` values until the child would become taller, then uses the last safe width as the final layout.
 - Known limitation: column shrink with `MultilineText` does not clip drawing by itself.
 
 ## Migration notes
@@ -139,3 +152,5 @@ Build the chat example:
 ```bash
 bun run example
 ```
+
+文本性能观测基线见 `docs/text-performance.md`。

package/example/chat.ts

@@ -7,6 +7,7 @@ import {
   MultilineText,
   PaddingBox,
   Place,
+  ShrinkWrap,
   Text,
   Wrapper,
   memoRenderItem,
@@ -357,7 +358,11 @@ const renderItem = memoRenderItem((item: ChatItem): Node<C> => {
     alignItems: item.sender === "A" ? "end" : "start",
   });
 
-  const alignedBody = new Place<C>(body, {
+  const shrinkWrappedBody = new ShrinkWrap<C>(body, {
+    preferredMinWidth: 160,
+  });
+
+  const alignedBody = new Place<C>(shrinkWrappedBody, {
     align: item.sender === "A" ? "end" : "start",
   });
 

package/index.d.mts

@@ -53,7 +53,7 @@ type TextWhiteSpaceMode = "normal" | "pre-wrap";
  */
 type TextOverflowMode = "clip" | "ellipsis";
 /**
- * Word breaking mode used by pretext during segmentation and line breaking.
+ * Word breaking mode used by the internal canvas text layout engine.
  */
 type TextWordBreakMode = "normal" | "keep-all";
 /**
@@ -74,9 +74,9 @@ interface TextStyleOptions<C extends CanvasRenderingContext2D> {
   font: string;
   /** Color or resolver used when drawing the text. */
   color: DynValue<C, string>;
-  /** Default: normal; matches pretext and CSS-style collapsible whitespace behavior. */
+  /** Default: normal; uses canvas-first CSS-style collapsible whitespace behavior. */
   whiteSpace?: TextWhiteSpaceMode;
-  /** Default: normal; use keep-all to match pretext's CJK-friendly line breaking mode. */
+  /** Default: normal; use keep-all for CJK-friendly line breaking. */
   wordBreak?: TextWordBreakMode;
   /** Default: break-word; use anywhere when min-content should honor grapheme break opportunities. */
   overflowWrap?: TextOverflowWrapMode;
@@ -91,9 +91,9 @@ interface InlineSpan<C extends CanvasRenderingContext2D> {
   font?: string;
   /** Color override for this fragment. Falls back to the node-level color. */
   color?: DynValue<C, string>;
-  /** Optional break hint forwarded to pretext rich-inline layout. */
+  /** Optional break hint for atomic inline spans. */
   break?: "normal" | "never";
-  /** Optional extra occupied width forwarded to pretext rich-inline layout. */
+  /** Optional extra occupied width appended after the span's rendered text. */
   extraWidth?: number;
 }
 /**
@@ -364,6 +364,24 @@ declare class Place<C extends CanvasRenderingContext2D> extends Wrapper<C> {
   hittest(ctx: Context<C>, test: HitTest): boolean;
 }
 //#endregion
+//#region src/nodes/shrinkwrap.d.ts
+interface ShrinkWrapOptions {
+  tolerance?: number;
+  preferredMinWidth?: number;
+}
+/**
+ * Shrinks a single child to the narrowest width that does not increase its reference height.
+ */
+declare class ShrinkWrap<C extends CanvasRenderingContext2D> extends Wrapper<C> {
+  #private;
+  readonly options: ShrinkWrapOptions;
+  constructor(inner: Node<C>, options?: ShrinkWrapOptions);
+  measure(ctx: Context<C>): Box;
+  measureMinContent(ctx: Context<C>): Box;
+  draw(ctx: Context<C>, x: number, y: number): boolean;
+  hittest(ctx: Context<C>, test: HitTest): boolean;
+}
+//#endregion
 //#region src/nodes/text.d.ts
 /**
  * Draws wrapped text using the configured line height and alignment.
@@ -658,5 +676,5 @@ declare class TimelineRenderer<C extends CanvasRenderingContext2D, T extends {}>
   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, ReplaceListItemAnimationOptions, Text, TextAlign, TextEllipsisPosition, TextOptions, TextOverflowMode, TextOverflowWrapMode, TextStyleOptions, TextWhiteSpaceMode, TextWordBreakMode, TimelineRenderer, VirtualizedRenderer, Wrapper, memoRenderItem, memoRenderItemBy };
+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, ReplaceListItemAnimationOptions, ShrinkWrap, Text, TextAlign, TextEllipsisPosition, TextOptions, TextOverflowMode, TextOverflowWrapMode, TextStyleOptions, TextWhiteSpaceMode, TextWordBreakMode, TimelineRenderer, VirtualizedRenderer, Wrapper, memoRenderItem, memoRenderItemBy };
 //# sourceMappingURL=index.d.mts.map