chat-layout 1.2.0-1 → 1.2.0-3

package/README.md

@@ -28,10 +28,11 @@ const bubble = new RoundedBox(
 );
 
 const body = new ShrinkWrap(
-  new Flex(
-    [senderLine, bubble],
-    { direction: "column", gap: 4, alignItems: item.sender === "A" ? "end" : "start" },
-  ),
+  new Flex([senderLine, bubble], {
+    direction: "column",
+    gap: 4,
+    alignItems: item.sender === "A" ? "end" : "start",
+  }),
 );
 
 const row = new Flex(
@@ -74,17 +75,20 @@ See [example/chat.ts](./example/chat.ts) for a full chat example.
 Single-line `Text` can ellipsize at the start, end, or middle when a finite width constraint is present:
 
 ```ts
-const title = new Text([
-  { text: "Extremely long " },
-  { text: "thread title", font: "700 16px system-ui", color: "#0f766e" },
-  { text: " that should not blow out the row" },
-], {
-  lineHeight: 20,
-  font: "16px system-ui",
-  color: "#111",
-  overflow: "ellipsis",
-  ellipsisPosition: "middle",
-});
+const title = new Text(
+  [
+    { text: "Extremely long " },
+    { text: "thread title", font: "700 16px system-ui", color: "#0f766e" },
+    { text: " that should not blow out the row" },
+  ],
+  {
+    lineHeight: 20,
+    font: "16px system-ui",
+    color: "#111",
+    overflow: "ellipsis",
+    ellipsisPosition: "middle",
+  },
+);
 ```
 
 Multi-line `MultilineText` can cap the visible line count and convert the last visible line to an end ellipsis:
@@ -109,6 +113,32 @@ 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.

package/example/chat.ts

@@ -37,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> {
@@ -164,7 +195,11 @@ const richTextMessage: InlineSpan<C>[] = [
   { text: "、" },
   { text: "粗体", font: "700 16px system-ui", color: "#b91c1c" },
   { text: "，以及 " },
-  { text: "inline code", font: "15px ui-monospace, SFMono-Regular, Consolas, monospace", color: "#7c3aed" },
+  {
+    text: "inline code",
+    font: "15px ui-monospace, SFMono-Regular, Consolas, monospace",
+    color: "#7c3aed",
+  },
   { text: " 这样的片段混排。" },
 ];
 
@@ -174,7 +209,11 @@ const richReplyPreview: InlineSpan<C>[] = [
   { text: "，比如 " },
   { text: "关键词高亮", color: "#2563eb" },
   { text: " 和 " },
-  { text: "code()", font: "12px ui-monospace, SFMono-Regular, Consolas, monospace", color: "#7c3aed" },
+  {
+    text: "code()",
+    font: "12px ui-monospace, SFMono-Regular, Consolas, monospace",
+    color: "#7c3aed",
+  },
   {
     text: "，超长内容仍然会按原来的两行省略规则收起，不需要额外处理。",
   },
@@ -203,13 +242,15 @@ class ItemDetector extends Wrapper<C> {
   hittest(_ctx: Context<C>, test: HitTest): boolean {
     currentHover = this.item;
     if (test.type === "click") {
-      const index = list.items.indexOf(this.item);
-      if (index < 0) {
+      if (!list.items.includes(this.item)) {
         return true;
       }
-      const nextItem = this.item.kind === "revoked" ? this.item.original : revokeMessage(this.item);
+      const nextItem =
+        this.item.kind === "revoked"
+          ? this.item.original
+          : revokeMessage(this.item);
       currentHover = nextItem;
-      list.replace(index, nextItem, {
+      list.update(this.item, nextItem, {
         duration: REPLACE_ANIMATION_DURATION,
       });
     }
@@ -235,8 +276,10 @@ const renderItem = memoRenderItem((item: ChatItem): Node<C> => {
               left: 12,
               right: 12,
               radii: 999,
-              fill: () => (currentHover?.id === item.id ? "#d9d9d9" : "#ececec"),
-              stroke: () => (currentHover?.id === item.id ? "#bcbcbc" : "#d3d3d3"),
+              fill: () =>
+                currentHover?.id === item.id ? "#d9d9d9" : "#ececec",
+              stroke: () =>
+                currentHover?.id === item.id ? "#bcbcbc" : "#d3d3d3",
             },
           ),
           {
@@ -290,6 +333,8 @@ const renderItem = memoRenderItem((item: ChatItem): Node<C> => {
       color: "black",
       align: "start",
       overflowWrap: "anywhere",
+      justify: "inter-character",
+      justifyGapThreshold: 0.2,
     }),
     { alignSelf: "start" },
   );
@@ -510,7 +555,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)]);
@@ -518,6 +563,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++,
@@ -553,12 +644,13 @@ button("jump latest (no anim)", () => {
 });
 
 button("revoke first", () => {
-  const item = list.items.find((entry): entry is MessageItem => entry.kind === "message");
+  const item = list.items.find(
+    (entry): entry is MessageItem => entry.kind === "message",
+  );
   if (item == null) {
     return;
   }
-  const index = list.items.indexOf(item);
-  list.replace(index, revokeMessage(item), {
+  list.update(item, revokeMessage(item), {
     duration: REPLACE_ANIMATION_DURATION,
   });
 });

package/example/test.ts

@@ -47,8 +47,10 @@ class RoundedBox extends PaddingBox<C> {
     // Reuse the current layout constraints so the background matches wrapped text.
     const { width, height } = ctx.measureNode(this, ctx.constraints);
     ctx.with((g) => {
-      const fill = this.fill == null ? undefined : ctx.resolveDynValue(this.fill);
-      const stroke = this.stroke == null ? undefined : ctx.resolveDynValue(this.stroke);
+      const fill =
+        this.fill == null ? undefined : ctx.resolveDynValue(this.fill);
+      const stroke =
+        this.stroke == null ? undefined : ctx.resolveDynValue(this.stroke);
       g.beginPath();
       g.roundRect(x, y, width, height, this.radii);
       if (fill != null) {

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. */
@@ -482,7 +509,7 @@ declare class DebugRenderer<C extends CanvasRenderingContext2D> extends BaseRend
 /**
  * Mutable list state shared with virtualized renderers.
  */
-interface ReplaceListItemAnimationOptions {
+interface UpdateListItemAnimationOptions {
   /** Animation duration in milliseconds. */
   duration?: number;
 }
@@ -509,9 +536,9 @@ declare class ListState<T extends {}> {
   /** Appends an array of items. */
   pushAll(items: T[]): void;
   /**
-   * Replaces an existing item by index.
+   * Updates an existing item by object identity.
    */
-  replace(index: number, item: T, animation?: ReplaceListItemAnimationOptions): void;
+  update(targetItem: T, nextItem: T, animation?: UpdateListItemAnimationOptions): void;
   /**
    * Sets the current anchor item and pixel offset.
    */
@@ -631,7 +658,7 @@ declare abstract class VirtualizedRenderer<C extends CanvasRenderingContext2D, T
   protected _finishRender(requestRedraw: boolean): boolean;
   protected _clampItemIndex(index: number): number;
   protected _getItemHeight(index: number): number;
-  protected _resolveItem(item: T, index: number, now: number): {
+  protected _resolveItem(item: T, _index: number, now: number): {
     value: VirtualizedResolvedItem<C>;
     height: number;
   };
@@ -676,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, ShrinkWrap, 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, ShrinkWrap, Text, TextAlign, TextEllipsisPosition, TextJustifyMode, TextJustifyOptions, TextOptions, TextOverflowMode, TextOverflowWrapMode, TextStyleOptions, TextWhiteSpaceMode, TextWordBreakMode, TimelineRenderer, UpdateListItemAnimationOptions, VirtualizedRenderer, Wrapper, memoRenderItem, memoRenderItemBy };
 //# sourceMappingURL=index.d.mts.map