chat-layout 1.0.0-1 → 1.0.0-3

package/README.md

@@ -1,201 +1,74 @@
 # chat-layout
 
-Canvas-based chat and timeline layout primitives with a v2 flex-style layout model.
+Canvas-based layout primitives for chat and timeline UIs.
 
-The current recommended APIs are:
+The current v2-style APIs are:
 
-- `Flex` for row/column layout
-- `FlexItem` for explicit `grow`
-- `Place` for single-child horizontal placement
-- `MultilineText` `align` / `physicalAlign` for text content alignment
-- `ChatRenderer` plus `ListState` for virtualized chat rendering
-- `memoRenderItem` for object items, or `memoRenderItemBy` when your stable key is primitive / explicit
+- `Flex`: row/column layout
+- `FlexItem`: explicit `grow` / `shrink` / `alignSelf`
+- `Place`: place a single child at `start` / `center` / `end`
+- `MultilineText`: text layout with logical `align` or physical `physicalAlign`
+- `ChatRenderer` + `ListState`: virtualized chat rendering
+- `memoRenderItem` / `memoRenderItemBy`: item render memoization
 
-**Layout Model**
-`Flex` and `Place` split layout concerns more clearly than the older API:
+## Quick example
 
-- Use `new Flex(children, { direction: "row" | "column" })` for main-axis layout.
-- Use `new FlexItem(child, { grow: 1 })` when a child should consume remaining space.
-- `Flex` shrink-wraps on the cross axis by default; `maxWidth` / `maxHeight` act as measurement caps rather than implicit fill signals.
-- Use `alignItems` / `alignSelf: "stretch"` when a specific child should fill the container's computed cross axis.
-- Use `new Place(child, { align: "start" | "center" | "end" })` when a single child should fill available width and then be placed left/center/right.
-- Use `justifyContent`, `alignItems`, and `alignSelf` for container/item placement.
-- Use `align: "start" | "center" | "end"` on `MultilineText` for logical alignment that matches `Place.align`.
-- Use `physicalAlign: "left" | "center" | "right"` on `MultilineText` only when you explicitly want physical left/right semantics.
-- `Text` / `MultilineText` preserve blank lines and edge whitespace by default; opt into cleanup with `whitespace: "trim-and-collapse"`.
-
-**Example**
-This is the recommended chat bubble shape used by [example/chat.ts](./example/chat.ts):
+Use `Flex` to build structure, `FlexItem` to control resize behavior, and `Place` to align the final bubble:
 
 ```ts
-type ChatItem = {
-  sender: string;
-  content: string;
-  reply?: {
-    sender: string;
-    content: string;
-  };
-};
-
-const renderItem = memoRenderItem((item: ChatItem): Node<C> => {
-  const senderLine = new Flex<C>(
-    [avatarDot, senderLabel],
-    {
-      direction: "row",
-      gap: 4,
-      mainAxisSize: "fit-content",
-      reverse: item.sender === "A",
-    },
-  );
-
-  const messageText = new FlexItem(
-    new MultilineText(item.content, {
-      lineHeight: 20,
-      font: "16px system-ui",
-      style: "black",
-      align: "start",
-    }),
-    { alignSelf: "start" },
-  );
-
-  const bubbleChildren: Node<C>[] = [];
-  if (item.reply != null) {
-    bubbleChildren.push(
-      new FlexItem(
-        new RoundedBox(
-          new Flex<C>(
-            [
-              new Text(item.reply.sender, {
-                lineHeight: 14,
-                font: "11px system-ui",
-                style: "#666",
-              }),
-              new MultilineText(item.reply.content, {
-                lineHeight: 16,
-                font: "13px system-ui",
-                style: "#444",
-                align: "start",
-              }),
-            ],
-            {
-              direction: "column",
-              gap: 2,
-              alignItems: "start",
-            },
-          ),
-          {
-            top: 5,
-            bottom: 5,
-            left: 8,
-            right: 8,
-            radii: 6,
-            fill: "#e2e2e2",
-          },
-        ),
-        { alignSelf: "stretch" },
-      ),
-    );
-  }
-  bubbleChildren.push(messageText);
-
-  const bubbleColumn = new Flex<C>(bubbleChildren, {
-    direction: "column",
-    gap: 6,
-    // The bubble itself stays intrinsic on the cross axis.
-    // Only the reply preview stretches to the bubble width.
-    alignItems: "start",
-  });
-
-  const content = new RoundedBox(
-    bubbleColumn,
-    {
-      top: 6,
-      bottom: 6,
-      left: 10,
-      right: 10,
-      radii: 8,
-      fill: "#ccc",
-    },
-  );
-
-  const body = new Flex<C>([senderLine, content], {
-    direction: "column",
-    alignItems: item.sender === "A" ? "end" : "start",
-  });
-
-  const alignedBody = new Place<C>(body, {
-    align: item.sender === "A" ? "end" : "start",
-  });
-
-  return new Place(
-    new PaddingBox(
-      new Flex<C>(
-        [
-          avatar,
-          new FlexItem(alignedBody, { grow: 1 }),
-          new Fixed(32, 0),
-        ],
-        {
-          direction: "row",
-          gap: 4,
-          reverse: item.sender === "A",
-        },
-      ),
-      {
-        top: 4,
-        bottom: 4,
-        left: 4,
-        right: 4,
-      },
-    ),
-    {
-      align: item.sender === "A" ? "end" : "start",
-    },
-  );
+const bubble = new RoundedBox(
+  new MultilineText(item.content, {
+    lineHeight: 20,
+    font: "16px system-ui",
+    style: "black",
+    align: "start",
+  }),
+  { top: 6, bottom: 6, left: 10, right: 10, radii: 8, fill: "#ccc" },
+);
+
+const row = new Flex(
+  [
+    avatar,
+    new FlexItem(bubble, { grow: 1, shrink: 1 }),
+  ],
+  { direction: "row", gap: 4, reverse: item.sender === "A" },
+);
+
+return new Place(row, {
+  align: item.sender === "A" ? "end" : "start",
 });
 ```
 
-That combination gives you:
-
-- explicit row/column structure
-- explicit grow behavior through `FlexItem`
-- left/right chat placement through `Place`
-- wrapped message bubbles that respect available width without becoming full-width by default
-- nested reply previews that use item-level cross-axis `stretch` to fill the bubble width
-
-In other words: a finite `maxWidth` / `maxHeight` limits measurement, but does not force the `Flex` container to fill the cross axis. If you want a child to fill the computed bubble width, mark that child with `alignSelf: "stretch"` (or inherit `alignItems: "stretch"` from the parent).
-
-## API notes
-
-- `memoRenderItem()` now only accepts object items. If your list item is a primitive or you want to memoize by an explicit id, use `memoRenderItemBy(keyOf, renderItem)`.
-- `FlexItemOptions` intentionally exposes only the implemented item-level controls: `grow` and `alignSelf`. The previously documented `shrink` / `basis` fields were removed because they were never implemented.
-- `ListState.position` now uses `undefined` as the explicit “use renderer default anchor” state. Use `list.setAnchor(position, offset)` to opt into a concrete anchor.
-- `ListState` can be seeded with `new ListState(items)` and reset with `list.reset(nextItems)`.
-- `MultilineText` now uses only `align` / `physicalAlign`; the old `alignment` field has been removed.
-
-### Migration notes
-
-- Before:
-  - `memoRenderItem((item: number) => ...)`
-- After:
-  - `memoRenderItemBy((item: number) => item, (item) => ...)`
-- Before:
-  - `new FlexItem(node, { grow: 1, shrink: 1, basis: 100 })`
-- After:
-  - `new FlexItem(node, { grow: 1 })`
-  - unsupported sizing semantics should be modeled explicitly in node measurement/layout instead of `shrink` / `basis`
-- Before:
-  - `new MultilineText(text, { alignment: "left" })`
-- After:
-  - `new MultilineText(text, { align: "start" })`
-  - or `new MultilineText(text, { physicalAlign: "left" })` when physical left/right semantics are required
-- Before:
-  - `list.position = Number.NaN`
-- After:
-  - `list.resetScroll()`
-  - or `list.setAnchor(index, offset)` for an explicit anchor
-
-**Development**
+See [example/chat.ts](./example/chat.ts) for a full chat example.
+
+## Layout notes
+
+- `Flex` handles the main axis only. It shrink-wraps on the cross axis unless you opt into stretch behavior.
+- `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.
+- `MultilineText.align` uses logical values: `start`, `center`, `end`.
+- `MultilineText.physicalAlign` uses physical values: `left`, `center`, `right`.
+- `Text` and `MultilineText` preserve blank lines and edge whitespace by default. Use `whitespace: "trim-and-collapse"` if you want cleanup.
+
+## 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.
+- Known limitation: column shrink with `MultilineText` does not clip drawing by itself.
+
+## Migration notes
+
+- Use `memoRenderItemBy(keyOf, renderItem)` when list items are primitives.
+- `FlexItem` exposes `grow`, `shrink`, and `alignSelf`; `basis` is no longer public.
+- `MultilineText` now uses `align` / `physicalAlign` instead of `alignment`.
+- `ListState.position` uses `undefined` for the renderer default anchor.
+- Use `list.resetScroll()` or `list.setAnchor(index, offset)` instead of assigning `Number.NaN`.
+
+## Development
+
 Install dependencies:
 
 ```bash

package/example/build.ts

@@ -0,0 +1,12 @@
+const { success, logs } = await Bun.build({
+  entrypoints: ["chat.ts"],
+  outdir: "build",
+});
+
+for (const log of logs) {
+  console.log(log);
+}
+
+if (!success) {
+  process.exit(1);
+}

package/example/chat.ts

@@ -0,0 +1,403 @@
+import {
+  ChatRenderer,
+  Flex,
+  FlexItem,
+  Fixed,
+  ListState,
+  MultilineText,
+  PaddingBox,
+  Place,
+  Text,
+  Wrapper,
+  memoRenderItem,
+  type Context,
+  type DynValue,
+  type HitTest,
+  type Node,
+  type RenderFeedback,
+} from "chat-layout";
+
+const sampleWords = [
+  "hello",
+  "world",
+  "chat",
+  "layout",
+  "message",
+  "render",
+  "bubble",
+  "timeline",
+  "virtualized",
+  "canvas",
+  "stream",
+  "session",
+  "update",
+  "typing",
+  "history",
+];
+
+type C = CanvasRenderingContext2D;
+
+class RoundedBox extends PaddingBox<C> {
+  readonly radii: number | DOMPointInit | (number | DOMPointInit)[];
+  readonly stroke: DynValue<C, string | undefined>;
+  readonly fill: DynValue<C, string | undefined>;
+
+  constructor(
+    inner: Node<C>,
+    {
+      radii,
+      stroke,
+      fill,
+      ...options
+    }: {
+      top?: number;
+      bottom?: number;
+      left?: number;
+      right?: number;
+      stroke?: DynValue<C, string | undefined>;
+      fill?: DynValue<C, string | undefined>;
+      radii: number | DOMPointInit | (number | DOMPointInit)[];
+    },
+  ) {
+    super(inner, options);
+    this.radii = radii;
+    this.stroke = stroke;
+    this.fill = fill;
+  }
+
+  draw(ctx: Context<C>, x: number, y: number): boolean {
+    // 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);
+      g.beginPath();
+      g.roundRect(x, y, width, height, this.radii);
+      if (fill != null) {
+        g.fillStyle = fill;
+      }
+      if (stroke != null) {
+        g.strokeStyle = stroke;
+      }
+      if (fill != null) {
+        g.fill();
+      }
+      if (stroke != null) {
+        g.stroke();
+      }
+    });
+    return super.draw(ctx, x, y);
+  }
+}
+
+class Circle extends Fixed<C> {
+  constructor(
+    readonly size: number,
+    readonly options: {
+      fill: DynValue<C, string>;
+    },
+  ) {
+    super(size, size);
+  }
+
+  draw(ctx: Context<C>, x: number, y: number): boolean {
+    ctx.with((g) => {
+      g.fillStyle = ctx.resolveDynValue(this.options.fill);
+      g.beginPath();
+      const radius = this.size / 2;
+      g.arc(x + radius, y + radius, radius, 0, 2 * Math.PI, false);
+      g.fill();
+    });
+    return false;
+  }
+}
+
+function button(text: string, action: () => void): void {
+  const btn = document.body.appendChild(document.createElement("button"));
+  btn.textContent = text;
+  btn.onclick = action;
+}
+
+const canvas = document.body.appendChild(document.createElement("canvas"));
+canvas.width = canvas.clientWidth * devicePixelRatio;
+canvas.height = canvas.clientHeight * devicePixelRatio;
+
+const context = canvas.getContext("2d");
+if (context == null) {
+  throw new Error("Failed to initial canvas");
+}
+const ctx: C = context;
+ctx.scale(devicePixelRatio, devicePixelRatio);
+
+type ChatItem = {
+  sender: string;
+  content: string;
+  reply?: {
+    sender: string;
+    content: string;
+  };
+};
+
+let currentHover: ChatItem | undefined;
+
+class HoverDetector extends Wrapper<C> {
+  constructor(
+    inner: Node<C>,
+    readonly item: ChatItem,
+  ) {
+    super(inner);
+  }
+
+  hittest(_ctx: Context<C>, _test: HitTest): boolean {
+    currentHover = this.item;
+    return true;
+  }
+}
+
+const renderItem = memoRenderItem((item: ChatItem): Node<C> => {
+  const senderLine = new Flex<C>(
+    [
+      new HoverDetector(
+        new Circle(15, {
+          fill: "blue",
+        }),
+        item,
+      ),
+      new RoundedBox(
+        new Text(item.sender, {
+          lineHeight: 15,
+          font: "12px system-ui",
+          style: "black",
+        }),
+        {
+          top: 0,
+          bottom: 0,
+          left: 0,
+          right: 0,
+          radii: 2,
+          fill: () => (currentHover === item ? "red" : "transparent"),
+        },
+      ),
+    ],
+    {
+      direction: "row",
+      gap: 4,
+      mainAxisSize: "fit-content",
+      reverse: item.sender === "A",
+    },
+  );
+
+  const messageText = new FlexItem(
+    new MultilineText(item.content, {
+      lineHeight: 20,
+      font: "16px system-ui",
+      style: "black",
+      align: "start",
+    }),
+    { alignSelf: "start" },
+  );
+
+  const bubbleChildren: Node<C>[] = [];
+  if (item.reply != null) {
+    const replyPreview = new FlexItem(
+      new RoundedBox(
+        new Flex<C>(
+          [
+            new Text(item.reply.sender, {
+              lineHeight: 14,
+              font: "11px system-ui",
+              style: () => (currentHover === item ? "#4d4d4d" : "#666"),
+            }),
+            new MultilineText(item.reply.content, {
+              lineHeight: 16,
+              font: "13px system-ui",
+              style: () => (currentHover === item ? "#222" : "#444"),
+              align: "start",
+            }),
+          ],
+          {
+            direction: "column",
+            gap: 2,
+            alignItems: "start",
+          },
+        ),
+        {
+          top: 5,
+          bottom: 5,
+          left: 8,
+          right: 8,
+          radii: 6,
+          fill: () => (currentHover === item ? "#c2c2c2" : "#e2e2e2"),
+        },
+      ),
+      { alignSelf: "stretch" },
+    );
+    bubbleChildren.push(replyPreview);
+  }
+  bubbleChildren.push(messageText);
+
+  const bubbleColumn = new Flex<C>(bubbleChildren, {
+    direction: "column",
+    gap: 6,
+    // The bubble itself shrink-wraps on the cross axis; only the reply preview stretches.
+    alignItems: "start",
+  });
+
+  const content = new RoundedBox(bubbleColumn, {
+    top: 6,
+    bottom: 6,
+    left: 10,
+    right: 10,
+    radii: 8,
+    fill: () => (currentHover === item ? "#aaa" : "#ccc"),
+  });
+
+  const body = new Flex<C>([senderLine, content], {
+    direction: "column",
+    gap: 4,
+    alignItems: item.sender === "A" ? "end" : "start",
+  });
+
+  const alignedBody = new Place<C>(body, {
+    align: item.sender === "A" ? "end" : "start",
+  });
+
+  const row = new Flex<C>(
+    [
+      new Circle(32, { fill: "red" }),
+      // Opt into shrink so narrow viewports wrap the bubble body instead of overflowing the row.
+      new FlexItem(alignedBody, { grow: 1, shrink: 1 }),
+      new Fixed(32, 0),
+    ],
+    {
+      direction: "row",
+      gap: 4,
+      reverse: item.sender === "A",
+    },
+  );
+
+  const padded = new PaddingBox(row, {
+    top: 4,
+    bottom: 4,
+    left: 4,
+    right: 4,
+  });
+
+  return new Place(padded, {
+    align: item.sender === "A" ? "end" : "start",
+  });
+});
+
+const list = new ListState<ChatItem>([
+  {
+    sender: "A",
+    content:
+      "hello world chat layout message render bubble timeline virtualized canvas",
+  },
+  {
+    sender: "B",
+    content: "aaaa",
+    reply: {
+      sender: "A",
+      content: "hello world chat layout message render",
+    },
+  },
+  { sender: "B", content: "aaaabbb" },
+  { sender: "B", content: "测试中文" },
+  { sender: "B", content: "测试aa中文aaa" },
+  {
+    sender: "A",
+    content: randomText(8),
+    reply: {
+      sender: "B",
+      content: "测试aa中文aaa",
+    },
+  },
+  { sender: "B", content: randomText(5) },
+]);
+const renderer = new ChatRenderer(ctx, {
+  renderItem,
+  list,
+});
+
+function drawFrame(): void {
+  const feedback: RenderFeedback = {
+    minIdx: Number.NaN,
+    maxIdx: Number.NaN,
+    min: Number.NaN,
+    max: Number.NaN,
+  };
+  renderer.render(feedback);
+
+  ctx.save();
+  ctx.textBaseline = "top";
+  ctx.font = "12px system-ui";
+  ctx.fillStyle = "black";
+  ctx.strokeStyle = "white";
+  ctx.lineWidth = 4;
+  ctx.lineJoin = "round";
+  const text = JSON.stringify(feedback);
+  ctx.strokeText(text, 10, 10);
+  ctx.fillText(text, 10, 10);
+  ctx.restore();
+
+  requestAnimationFrame(drawFrame);
+}
+
+requestAnimationFrame(drawFrame);
+
+canvas.addEventListener("wheel", (e) => {
+  list.applyScroll(-e.deltaY);
+});
+
+canvas.addEventListener("pointermove", (e) => {
+  const { top, left } = canvas.getBoundingClientRect();
+  const result = renderer.hittest({
+    x: e.clientX - left,
+    y: e.clientY - top,
+    type: "hover",
+  });
+  if (!result) {
+    currentHover = undefined;
+  }
+});
+
+function randomText(words: number): string {
+  const out: string[] = [];
+  for (let i = 0; i < words; i += 1) {
+    out.push(sampleWords[Math.floor(Math.random() * sampleWords.length)]);
+  }
+  return out.join(" ");
+}
+
+button("unshift", () => {
+  list.unshift({
+    sender: Math.random() < 0.5 ? "A" : "B",
+    content: randomText(10 + Math.floor(200 * Math.random())),
+  });
+});
+
+button("push", () => {
+  list.push({
+    sender: Math.random() < 0.5 ? "A" : "B",
+    content: randomText(10 + Math.floor(200 * Math.random())),
+  });
+});
+
+button("jump middle", () => {
+  renderer.jumpTo(Math.floor(list.items.length / 2));
+});
+
+button("jump middle (center)", () => {
+  renderer.jumpTo(Math.floor(list.items.length / 2), {
+    block: "center",
+  });
+});
+
+button("jump latest (no anim)", () => {
+  renderer.jumpTo(list.items.length - 1, {
+    animated: false,
+  });
+});