chat-layout 1.2.0-0 → 1.2.0-2

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,6 +58,7 @@ 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"`, using the library's canvas-first collapsible whitespace behavior.
@@ -97,12 +109,39 @@ Notes:
 - `overflowWrap: "break-word"` keeps the current min-content behavior; `overflowWrap: "anywhere"` lets long unspaced strings shrink inside flex layouts such as chat bubbles.
 - Current `measureMinContent()` behavior stays compatibility-first: ellipsis affects constrained measurement/drawing, but does not lower the min-content shrink floor by itself.
 
+## Text justification
+
+`MultilineText` supports two-end justification (justify) as a draw-phase decoration. It does not affect measurement or layout:
+
+```ts
+const justified = new MultilineText(paragraph, {
+  lineHeight: 20,
+  font: "16px system-ui",
+  color: "#111",
+  align: "start",
+  justify: true,               // or "inter-word" | "inter-character"
+  justifyLastLine: false,       // default: last line uses normal alignment
+  justifyGapThreshold: 2.0,    // max gap ratio before fallback
+});
+```
+
+Notes:
+
+- `justify: true` is equivalent to `"inter-word"` mode, which expands spaces between words via `ctx.wordSpacing`.
+- `"inter-character"` mode distributes extra space after every character via `ctx.letterSpacing`.
+- Requires browser support for `CanvasRenderingContext2D.wordSpacing` / `letterSpacing`. When unsupported, justify is silently disabled.
+- Lines that exceed `justifyGapThreshold`, have no expandable gaps, or are the last line (unless `justifyLastLine: true`) fall back to `align` / `physicalAlign`.
+- `overflow: "ellipsis"` truncated lines are never justified.
+- `measure()` and `measureMinContent()` are not affected by justify options.
+- Works with both plain text and `InlineSpan[]` rich text.
+
 ## Shrink behavior
 
 - `FlexItemOptions.shrink` defaults to `0`, so old layouts keep their previous behavior unless you opt in.
 - 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

package/example/chat.ts

@@ -7,6 +7,7 @@ import {
   MultilineText,
   PaddingBox,
   Place,
+  ShrinkWrap,
   Text,
   Wrapper,
   memoRenderItem,
@@ -36,6 +37,37 @@ const sampleWords = [
   "history",
 ];
 
+const sampleChinesePhrases = [
+  "你好",
+  "收到",
+  "没问题",
+  "等一下",
+  "马上来",
+  "这个效果不错",
+  "刚刚更新了",
+  "看起来可以",
+  "再确认一下",
+  "这里有点奇怪",
+  "我先试试",
+  "辛苦了",
+  "已经修好了",
+  "周会上再聊",
+  "我发你截图",
+];
+
+const sampleMixedPhrases = [
+  "hello 这条消息现在支持中文了",
+  "chat layout 这里需要再看一下",
+  "render 完成后记得刷新 preview",
+  "这段 mixed text 会测试自动换行 behavior",
+  "reply preview 里也放一点中文 content",
+  "今天的 build 已经 green 了",
+  "这个 bubble 的 spacing 感觉更自然",
+  "virtualized 列表滚动起来还是很顺",
+  "先 push 一个 demo message 看效果",
+  "中文 English mixed 排版更接近真实聊天",
+];
+
 type C = CanvasRenderingContext2D;
 
 class RoundedBox extends PaddingBox<C> {
@@ -289,6 +321,8 @@ const renderItem = memoRenderItem((item: ChatItem): Node<C> => {
       color: "black",
       align: "start",
       overflowWrap: "anywhere",
+      justify: "inter-character",
+      justifyGapThreshold: 0.2,
     }),
     { alignSelf: "start" },
   );
@@ -357,7 +391,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",
   });
 
@@ -505,7 +543,7 @@ canvas.addEventListener("click", (e) => {
   }
 });
 
-function randomText(words: number): string {
+function randomEnglishText(words: number): string {
   const out: string[] = [];
   for (let i = 0; i < words; i += 1) {
     out.push(sampleWords[Math.floor(Math.random() * sampleWords.length)]);
@@ -513,6 +551,52 @@ function randomText(words: number): string {
   return out.join(" ");
 }
 
+function randomChineseText(words: number): string {
+  const out: string[] = [];
+  for (let i = 0; i < words; i += 1) {
+    out.push(
+      sampleChinesePhrases[
+        Math.floor(Math.random() * sampleChinesePhrases.length)
+      ],
+    );
+  }
+  return out.join("");
+}
+
+function randomMixedText(words: number): string {
+  const out: string[] = [];
+  for (let i = 0; i < words; i += 1) {
+    const mode = Math.random();
+    if (mode < 0.2) {
+      out.push(sampleWords[Math.floor(Math.random() * sampleWords.length)]);
+      continue;
+    }
+    if (mode < 0.65) {
+      out.push(
+        sampleChinesePhrases[
+          Math.floor(Math.random() * sampleChinesePhrases.length)
+        ],
+      );
+      continue;
+    }
+    out.push(
+      sampleMixedPhrases[Math.floor(Math.random() * sampleMixedPhrases.length)],
+    );
+  }
+  return out.join(Math.random() < 0.5 ? " " : "");
+}
+
+function randomText(words: number): string {
+  const mode = Math.random();
+  if (mode < 0.3) {
+    return randomEnglishText(words);
+  }
+  if (mode < 0.6) {
+    return randomChineseText(words);
+  }
+  return randomMixedText(words);
+}
+
 button("unshift", () => {
   list.unshift({
     id: nextMessageId++,

package/index.d.mts

@@ -96,10 +96,37 @@ interface InlineSpan<C extends CanvasRenderingContext2D> {
   /** Optional extra occupied width appended after the span's rendered text. */
   extraWidth?: number;
 }
+/**
+ * Two-end justification mode for multi-line text.
+ * `"inter-word"` expands only collapsible spaces.
+ * `"inter-character"` is script-aware and may combine `wordSpacing` with `letterSpacing`.
+ */
+type TextJustifyMode = "inter-word" | "inter-character";
+/**
+ * Options controlling two-end justification behavior.
+ */
+interface TextJustifyOptions {
+  /**
+   * Enable two-end justification. Default: false.
+   * `true` uses "inter-word" mode.
+   * `"inter-character"` may combine `wordSpacing` and `letterSpacing` internally.
+   */
+  justify?: boolean | TextJustifyMode;
+  /**
+   * Whether to justify the last line as well. Default: false.
+   */
+  justifyLastLine?: boolean;
+  /**
+   * Maximum ratio of a single gap relative to the average word/char width.
+   * Lines exceeding this threshold fall back to normal alignment.
+   * Default: 2.0. Set to Infinity to disable.
+   */
+  justifyGapThreshold?: number;
+}
 /**
  * Options for multi-line text nodes.
  */
-interface MultilineTextOptions<C extends CanvasRenderingContext2D> extends TextStyleOptions<C> {
+interface MultilineTextOptions<C extends CanvasRenderingContext2D> extends TextStyleOptions<C>, TextJustifyOptions {
   /** Logical alignment that matches `Place.align`. */
   align?: TextAlign;
   /** Explicit physical alignment when left/right semantics are required. */
@@ -364,6 +391,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 +703,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, TextJustifyMode, TextJustifyOptions, TextOptions, TextOverflowMode, TextOverflowWrapMode, TextStyleOptions, TextWhiteSpaceMode, TextWordBreakMode, TimelineRenderer, VirtualizedRenderer, Wrapper, memoRenderItem, memoRenderItemBy };
 //# sourceMappingURL=index.d.mts.map