@octohirono/stitch-design-system 0.2.0 → 0.3.0

package/dist/components/ChatFile/ChatFile.d.ts

@@ -0,0 +1,34 @@
+import React from 'react';
+/**
+ * 文件附件卡：复用 `<Card>` 承载——类型图标（`<Icon name="file">`）+ 文件名 + 大小 /
+ * 副文本；作为 `<ChatMessage>` 的 `content` 塞入（sent / received 两侧皆可）。点击 / 下载
+ * 均为**回调交 app**（组件不导航、不发起下载）。对外 props 取 Ant Design X `Attachments`
+ * 附件项最近惯例（`name` / `size` / `description`）+ Ant v5 回调命名。
+ *
+ * 跨-prop 注意事项：
+ * - **下载键是文件卡固有部件、常驻**（文件默认可下载）：右侧复用 `<Button type="text">`，点击走
+ *   `onDownload` 回调、由 app 落地下载。
+ * - **两个独立可聚焦控件、互不嵌套**：给 `onClick` 时文件名区升格为整行透明按钮（打开），与下载
+ *   键平级，无按钮套按钮。
+ * - **`size` 是字节数**，组件内格式化为人类可读（`1.2 MB`）；`description` 为副文本（如类型），
+ *   与已格式化的大小同排、`·` 分隔。
+ * - **图标走 `<Icon>`**：类型图标 `<Icon name="file">`（装饰性）、下载 `<Icon name="download">`
+ *   （其按钮带可访问名 `下载 {name}`），非 emoji / 裸 `<svg>`。
+ */
+export interface ChatFileProps {
+    /** 文件名（必填） */
+    name: string;
+    /** 文件大小（字节数）；组件内格式化为人类可读 */
+    size?: number;
+    /** 副文本（如文件类型说明），与大小同排 `·` 分隔 */
+    description?: React.ReactNode;
+    /** 点击文件卡的回调（打开 / 预览交 app）；给出时文件名区可聚焦、可键盘触发 */
+    onClick?: () => void;
+    /** 点击下载键的回调（下载交 app）；下载键常驻，点击走此回调 */
+    onDownload?: () => void;
+    /** 自定义类名（挂到根 Card） */
+    className?: string;
+    /** 行内样式（挂到根 Card） */
+    style?: React.CSSProperties;
+}
+export declare const ChatFile: React.FC<ChatFileProps>;

package/dist/components/ChatFile/ChatFile.js

@@ -0,0 +1,71 @@
+import { Button as e } from "../Button/Button.js";
+import { Icon as t } from "../Icon/Icon.js";
+import { Card as n } from "../Card/Card.js";
+import r from "./chat-file.module.js";
+import "react";
+import i from "clsx";
+import { Fragment as a, jsx as o, jsxs as s } from "react/jsx-runtime";
+//#region packages/react/src/components/ChatFile/ChatFile.tsx
+var c = [
+	"B",
+	"KB",
+	"MB",
+	"GB",
+	"TB"
+];
+function l(e) {
+	if (!Number.isFinite(e) || e < 0) return "";
+	if (e < 1) return "0 B";
+	let t = Math.min(c.length - 1, Math.floor(Math.log(e) / Math.log(1024))), n = e / 1024 ** t;
+	return `${t === 0 ? String(Math.round(n)) : n.toFixed(1)} ${c[t]}`;
+}
+var u = ({ name: c, size: u, description: d, onClick: f, onDownload: p, className: m, style: h }) => {
+	let g = typeof u == "number" ? l(u) : "", _ = /* @__PURE__ */ s("span", {
+		className: r.meta,
+		children: [
+			g && /* @__PURE__ */ o("span", { children: g }),
+			g && d != null && /* @__PURE__ */ o("span", {
+				"aria-hidden": "true",
+				children: " · "
+			}),
+			d != null && /* @__PURE__ */ o("span", { children: d })
+		]
+	}), v = /* @__PURE__ */ s(a, { children: [/* @__PURE__ */ o(t, {
+		name: "file",
+		className: r.type,
+		size: "1.5em"
+	}), /* @__PURE__ */ s("span", {
+		className: r.text,
+		children: [/* @__PURE__ */ o("span", {
+			className: r.name,
+			children: c
+		}), (g || d != null) && _]
+	})] });
+	return /* @__PURE__ */ s(n, {
+		variant: "outlined",
+		className: i(r.file, m),
+		style: h,
+		children: [f ? /* @__PURE__ */ o("button", {
+			type: "button",
+			className: r.trigger,
+			onClick: f,
+			"aria-label": `打开文件 ${c}`,
+			children: v
+		}) : /* @__PURE__ */ o("div", {
+			className: r.trigger,
+			children: v
+		}), /* @__PURE__ */ o(e, {
+			type: "text",
+			className: r.download,
+			onClick: p,
+			"aria-label": `下载 ${c}`,
+			children: /* @__PURE__ */ o(t, {
+				name: "download",
+				size: "1.25em"
+			})
+		})]
+	});
+};
+u.displayName = "ChatFile";
+//#endregion
+export { u as ChatFile };

package/dist/components/ChatFile/chat-file.module.js

@@ -0,0 +1,12 @@
+//#region packages/react/src/components/ChatFile/chat-file.module.less
+var e = "_file_1tjaq_1", t = "_trigger_1tjaq_8", n = "_type_1tjaq_29", r = "_text_1tjaq_33", i = "_name_1tjaq_39", a = "_meta_1tjaq_47", o = "_download_1tjaq_51", s = {
+	file: e,
+	trigger: t,
+	type: n,
+	text: r,
+	name: i,
+	meta: a,
+	download: o
+};
+//#endregion
+export { s as default, o as download, e as file, a as meta, i as name, r as text, t as trigger, n as type };

package/dist/components/ChatFile/index.d.ts

@@ -0,0 +1,2 @@
+export { ChatFile } from './ChatFile';
+export type { ChatFileProps } from './ChatFile';

package/dist/components/ChatImage/ChatImage.d.ts

@@ -0,0 +1,31 @@
+import React from 'react';
+/**
+ * 图片消息（气泡内缩略图 + 大图查看器）：气泡里显缩略图（复用通用 `<Image>`、`preview` 关闭），
+ * 点击开大图——**大图仍复用通用 `<Image>`（它自带的相框即「框」）**，本组件只做一层遮罩 + 把下载 /
+ * 关闭工具键**叠在这个框上**。作为 `<ChatMessage>` 的 `content` 塞入（sent / received 两侧皆可）。
+ * `src` / `alt` / `width` / `height` 照搬 antd `Image`；`width` 即缩略图宽。
+ *
+ * 跨-prop 注意事项：
+ * - **缩略图与大图都复用 `<Image preview={false}>`**（不手写裸 `<img>`、不重造 Image 的相框 / 圆角 /
+ *   加载淡入 / 错误占位）；本组件只加聊天专属的遮罩 + 框上工具键（下载 / 关闭），`<Image>` 一行未改。
+ * - **块级排布**：根为块级元素，故 `<ChatMessage>` 的时间 / 回执落在缩略图**下方**（同文件卡）。
+ * - **大图查看器 a11y**：Portal 遮罩 + `role="dialog"`；打开焦点落关闭键、Tab 在下载 / 关闭间循环、
+ *   ESC 关闭、关闭后焦点归还缩略图。下载走原生 `<a download href={src}>`（存下当前图，不解码不发
+ *   请求），工具键图标走 `<Icon>`，均带可访问名。
+ * - `width` 控缩略图尺寸；点击后大图按视口放大（原始尺寸）。
+ */
+export interface ChatImageProps {
+    /** 图片地址（必填，照搬 antd Image） */
+    src: string;
+    /** 图片替代文本（无障碍）；留空表示装饰性图片 */
+    alt?: string;
+    /** 缩略图宽度（数字按 px，字符串原样） */
+    width?: number | string;
+    /** 缩略图高度（数字按 px，字符串原样） */
+    height?: number | string;
+    /** 自定义类名（挂到根） */
+    className?: string;
+    /** 行内样式（挂到根） */
+    style?: React.CSSProperties;
+}
+export declare const ChatImage: React.FC<ChatImageProps>;

package/dist/components/ChatImage/ChatImage.js

@@ -0,0 +1,88 @@
+import { Icon as e } from "../Icon/Icon.js";
+import { Image as t } from "../Image/Image.js";
+import n from "./chat-image.module.js";
+import { useEffect as r, useRef as i, useState as a } from "react";
+import o from "clsx";
+import { jsx as s, jsxs as c } from "react/jsx-runtime";
+import { createPortal as l } from "react-dom";
+//#region packages/react/src/components/ChatImage/ChatImage.tsx
+var u = ({ src: u, alt: d = "", width: f, height: p, className: m, style: h }) => {
+	let [g, _] = a(!1), v = i(null), y = i(null), b = i(null);
+	return r(() => {
+		if (!g) return;
+		v.current?.focus();
+		let e = (e) => {
+			if (e.key === "Escape") _(!1);
+			else if (e.key === "Tab") {
+				e.preventDefault();
+				let t = [y.current, v.current].filter((e) => e != null);
+				if (t.length === 0) return;
+				let n = t.indexOf(document.activeElement);
+				t[e.shiftKey ? n <= 0 ? t.length - 1 : n - 1 : n >= t.length - 1 ? 0 : n + 1]?.focus();
+			}
+		};
+		return document.addEventListener("keydown", e), () => document.removeEventListener("keydown", e);
+	}, [g]), r(() => {
+		g || (b.current?.focus(), b.current = null);
+	}, [g]), /* @__PURE__ */ c("span", {
+		className: o(n.frame, m),
+		style: h,
+		children: [/* @__PURE__ */ s("button", {
+			type: "button",
+			className: n.thumb,
+			onClick: () => {
+				b.current = document.activeElement, _(!0);
+			},
+			"aria-label": d ? `查看大图 ${d}` : "查看大图",
+			children: /* @__PURE__ */ s(t, {
+				src: u,
+				alt: d,
+				width: f,
+				height: p,
+				preview: !1
+			})
+		}), l(g ? /* @__PURE__ */ s("div", {
+			className: n.mask,
+			onClick: () => _(!1),
+			children: /* @__PURE__ */ c("div", {
+				className: n.dialog,
+				role: "dialog",
+				"aria-modal": "true",
+				"aria-label": d ? `查看图片：${d}` : "图片预览",
+				onClick: (e) => e.stopPropagation(),
+				children: [/* @__PURE__ */ s(t, {
+					src: u,
+					alt: d,
+					preview: !1,
+					className: n.full
+				}), /* @__PURE__ */ c("div", {
+					className: n.tools,
+					children: [/* @__PURE__ */ s("a", {
+						ref: y,
+						className: n.toolBtn,
+						href: u,
+						download: !0,
+						"aria-label": d ? `下载图片 ${d}` : "下载图片",
+						children: /* @__PURE__ */ s(e, {
+							name: "download",
+							size: 14
+						})
+					}), /* @__PURE__ */ s("button", {
+						type: "button",
+						ref: v,
+						className: n.toolBtn,
+						"aria-label": "关闭大图",
+						onClick: () => _(!1),
+						children: /* @__PURE__ */ s(e, {
+							name: "close",
+							size: 14
+						})
+					})]
+				})]
+			})
+		}) : null, document.body)]
+	});
+};
+u.displayName = "ChatImage";
+//#endregion
+export { u as ChatImage };

package/dist/components/ChatImage/chat-image.module.js

@@ -0,0 +1,12 @@
+//#region packages/react/src/components/ChatImage/chat-image.module.less
+var e = "_frame_1b4n8_1", t = "_thumb_1b4n8_6", n = "_mask_1b4n8_18", r = "_dialog_1b4n8_27", i = "_full_1b4n8_32", a = "_tools_1b4n8_36", o = "_toolBtn_1b4n8_44", s = {
+	frame: e,
+	thumb: t,
+	mask: n,
+	dialog: r,
+	full: i,
+	tools: a,
+	toolBtn: o
+};
+//#endregion
+export { s as default, r as dialog, e as frame, i as full, n as mask, t as thumb, o as toolBtn, a as tools };

package/dist/components/ChatImage/index.d.ts

@@ -0,0 +1,2 @@
+export { ChatImage } from './ChatImage';
+export type { ChatImageProps } from './ChatImage';

package/dist/components/ChatInput/ChatInput.d.ts

@@ -0,0 +1,77 @@
+import React from 'react';
+export type ChatInputSubmitType = 'enter' | 'shiftEnter';
+/** autoSize 精细档：限制自增高的最小 / 最大行数（照搬 antd Input.TextArea / Sender） */
+export interface ChatInputAutoSize {
+    /** 最小行数（低于此仍占此高） */
+    minRows?: number;
+    /** 最大行数（超过后内部滚动、不再增高） */
+    maxRows?: number;
+}
+/**
+ * 聊天输入器：多行 textarea **自增高**（`autoSize`）+ 受控/非受控 `value` + `submitType`
+ * 决定发送键位（Enter 发送 / Shift+Enter 换行）+ `onSubmit` 发送回调 + `prefix` / `actions`
+ * 插槽（附件按钮等钩子由 app 填）。对外 props 照搬 antd `Input`（`value` / `onChange` /
+ * `disabled` / `placeholder` / `autoSize`）+ 聊天专属补 Ant Design X `Sender`
+ * （`onSubmit` / `loading` / `submitType` / `prefix` / `actions`）。
+ *
+ * 跨-prop 注意事项：
+ * - **受控/非受控双模式**：给 `value` 由父管，只给 `defaultValue` 组件自管；非受控时发送后
+ *   自动清空，受控时清空由父在 `onSubmit` 里做（组件不擅自改父的值）。
+ * - **`autoSize` 自增高**：`true`（默认）随内容行数增高；传 `{ minRows, maxRows }` 卡上下界，
+ *   超 `maxRows` 内部滚动。`false` 关自增（固定单行高、可手动拉伸由浏览器定）。
+ * - **`submitType` 定发送键位**：`enter`（默认）→ Enter 发送、Shift+Enter 换行；`shiftEnter`
+ *   → Shift+Enter 发送、Enter 换行。输入法组词中（IME composing）的 Enter 一律只上屏、不发送。
+ * - **`onSubmit` 只在有内容时触发**：纯空白不发送；`disabled` / `loading` 时不发送。发送键是
+ *   原生 `<button>`，图标走 `<Icon name="send">`（禁 emoji / Unicode / 裸 svg），`sendAriaLabel`
+ *   定其可访问名。
+ * - **IM 无停止态**：`loading` 只置发送键忙 / 禁发，**不**把发送键换成「停止」键（那是 AI 生成
+ *   语境；IM 是人对人、无生成可停）。
+ * - **`prefix` / `actions` 传你自己的元素**（附件按钮走 `<Icon>` 或 `<Button>`）——**Do NOT** 传
+ *   emoji / Unicode 符号 / 裸 `<svg>`。附件的选择 / 上传逻辑由 app 实现，组件只留插槽。
+ * - **可及名**：其余原生 textarea 属性（`aria-label` / `id` / `name` / `maxLength` …）经 `...rest`
+ *   透传到内部 `<textarea>`——给它可访问名（配 `<label htmlFor>` 或 `aria-label`）。
+ */
+export interface ChatInputProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'defaultValue' | 'onChange' | 'onSubmit' | 'onKeyDown' | 'rows' | 'prefix'> {
+    /** 输入值（受控）；不传由组件自管（非受控，配 `defaultValue`） */
+    value?: string;
+    /** 默认值（非受控初始值） */
+    defaultValue?: string;
+    /** 值变化回调（照搬 antd Input） */
+    onChange?: React.ChangeEventHandler<HTMLTextAreaElement>;
+    /** 发送回调（照搬 Ant Design X Sender）：参数为当前消息文本 */
+    onSubmit?: (message: string) => void;
+    /** 占位符（照搬 antd Input） */
+    placeholder?: string;
+    /** 禁用（照搬 antd Input） */
+    disabled?: boolean;
+    /**
+     * 发送中（照搬 Sender）：置发送键忙 / 禁发；**IM 无停止态**，不换成「停止」键
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * 多行自增高（照搬 antd Input.TextArea / Sender）：`true` 随内容增高，`{ minRows, maxRows }`
+     * 卡上下界，`false` 关自增
+     * @default true
+     */
+    autoSize?: boolean | ChatInputAutoSize;
+    /**
+     * 发送键位（照搬 Sender）：`enter` = Enter 发送 / Shift+Enter 换行；`shiftEnter` 反之
+     * @default 'enter'
+     */
+    submitType?: ChatInputSubmitType;
+    /** 前缀插槽（附件按钮等钩子，照搬 Sender）；附件逻辑由 app */
+    prefix?: React.ReactNode;
+    /** 动作区插槽（照搬 Sender）：覆盖默认发送键旁的自定义动作 */
+    actions?: React.ReactNode;
+    /**
+     * 发送键的无障碍标签（纯图标按钮必备可访问名）
+     * @default '发送'
+     */
+    sendAriaLabel?: string;
+    /** 自定义类名（挂到根容器） */
+    className?: string;
+    /** 行内样式（挂到根容器） */
+    style?: React.CSSProperties;
+}
+export declare const ChatInput: React.FC<ChatInputProps>;

package/dist/components/ChatInput/ChatInput.js

@@ -0,0 +1,88 @@
+import { Icon as e } from "../Icon/Icon.js";
+import t from "./chat-input.module.js";
+import { useCallback as n, useLayoutEffect as r, useRef as i, useState as a } from "react";
+import o from "clsx";
+import { jsx as s, jsxs as c } from "react/jsx-runtime";
+//#region packages/react/src/components/ChatInput/ChatInput.tsx
+var l = 1, u = ({ value: u, defaultValue: d, onChange: f, onSubmit: p, placeholder: m, disabled: h = !1, loading: g = !1, autoSize: _ = !0, submitType: v = "enter", prefix: y, actions: b, sendAriaLabel: x = "发送", className: S, style: C, ...w }) => {
+	let [T, E] = a(d ?? ""), D = u !== void 0, O = D ? u : T, k = i(null), A = n(() => {
+		let e = k.current;
+		if (e == null || _ === !1) return;
+		let t = _ === !0 ? {} : _, n = parseFloat(window.getComputedStyle(e).lineHeight) || 0;
+		e.style.height = "auto";
+		let r = e.scrollHeight;
+		if (n > 0) {
+			let i = t.minRows ?? l;
+			if (r = Math.max(r, i * n), t.maxRows != null) {
+				let i = t.maxRows * n;
+				e.style.overflowY = r > i ? "auto" : "hidden", r = Math.min(r, i);
+			} else e.style.overflowY = "hidden";
+		}
+		e.style.height = `${r}px`;
+	}, [_]);
+	r(() => {
+		A();
+	}, [O, A]), r(() => {
+		let e = k.current;
+		if (e == null || _ === !1 || typeof ResizeObserver > "u") return;
+		let t = -1, n = new ResizeObserver((e) => {
+			let n = e[0].contentRect.width;
+			n !== t && (t = n, A());
+		});
+		return n.observe(e), () => n.disconnect();
+	}, [_, A]);
+	let j = n((e) => {
+		D || E(e.target.value), f?.(e);
+	}, [D, f]), M = n(() => {
+		if (h || g) return;
+		let e = O;
+		e.trim() !== "" && (p?.(e), D || E(""));
+	}, [
+		h,
+		g,
+		O,
+		p,
+		D
+	]), N = n((e) => {
+		e.key === "Enter" && (e.nativeEvent.isComposing || (v === "enter" ? !e.shiftKey : e.shiftKey) && (e.preventDefault(), M()));
+	}, [v, M]), P = !h && !g && O.trim() !== "";
+	return /* @__PURE__ */ c("div", {
+		className: o(t.input, h && t["is-disabled"], S),
+		style: C,
+		children: [
+			y != null && /* @__PURE__ */ s("div", {
+				className: t.prefix,
+				children: y
+			}),
+			/* @__PURE__ */ s("textarea", {
+				ref: k,
+				className: t.textarea,
+				value: O,
+				placeholder: m,
+				disabled: h,
+				rows: 1,
+				onChange: j,
+				onKeyDown: N,
+				...w
+			}),
+			/* @__PURE__ */ c("div", {
+				className: t.actions,
+				children: [b, /* @__PURE__ */ s("button", {
+					type: "button",
+					className: t.send,
+					onClick: M,
+					disabled: !P,
+					"aria-label": x,
+					"aria-busy": g || void 0,
+					children: /* @__PURE__ */ s(e, {
+						name: "send",
+						size: 20
+					})
+				})]
+			})
+		]
+	});
+};
+u.displayName = "ChatInput";
+//#endregion
+export { u as ChatInput };

package/dist/components/ChatInput/chat-input.module.js

@@ -0,0 +1,11 @@
+//#region packages/react/src/components/ChatInput/chat-input.module.less
+var e = "_input_1o9t1_1", t = "_prefix_1o9t1_27", n = "_textarea_1o9t1_32", r = "_actions_1o9t1_56", i = "_send_1o9t1_62", a = {
+	input: e,
+	"is-disabled": "_is-disabled_1o9t1_15",
+	prefix: t,
+	textarea: n,
+	actions: r,
+	send: i
+};
+//#endregion
+export { r as actions, a as default, e as input, t as prefix, i as send, n as textarea };

package/dist/components/ChatInput/index.d.ts

@@ -0,0 +1,2 @@
+export { ChatInput } from './ChatInput';
+export type { ChatInputProps, ChatInputSubmitType, ChatInputAutoSize, } from './ChatInput';

package/dist/components/ChatList/ChatList.d.ts

@@ -0,0 +1,58 @@
+import React from 'react';
+import type { ChatMessageProps, ChatMessageVariant } from '../ChatMessage';
+/** 单条消息数据 = 一条 `ChatMessage` 的 props + 稳定 `id`（React key + append 判定） */
+export interface ChatListItem extends ChatMessageProps {
+    /** 唯一标识：作 React key，并驱动「新消息 append」判定 */
+    id: string | number;
+}
+/**
+ * 消息流容器：**数据驱动**——吃 `items`（每项 = 一条 `ChatMessage` 的 props + `id`），内部
+ * 渲染 `ChatMessage`（`ChatMessage` 仍可单独使用，列表场景走 `items`）。负责连发分组编排、
+ * 贴底滚动与向上加载历史的接缝。对外 props 照搬 Ant Design X `Bubble.List`（`items` / `roles` /
+ * `autoScroll`），加载更多接缝取 Ant `on*` 惯例。
+ *
+ * 跨-prop 注意事项：
+ * - **数据驱动、组件不算业务**：消息内容 / 时间 / 头像 / 已读态全由 `items` 每项自带（就是
+ *   `ChatMessageProps`）；组件只按数组顺序渲染，不排序、不去重、不算时间。
+ * - **`roles` 灌角色默认**：按 `variant` 给同类消息灌共享默认（如 received 统一头像），`item`
+ *   显式字段优先覆盖 `roles` 默认（照 Ant X `roles`）。
+ * - **连发分组自动编排**：相邻同 `variant`（非 system）的续条自动置 `ChatMessage` 的 `grouped`
+ *   ——头像只在组内首条显示、组内间距收紧（**不合并内容，仍是多个独立气泡**）。`system` 项
+ *   （如日期分隔）断组。`item` 显式传 `grouped` 时以其为准。
+ * - **日期分隔 = `system` 项**：日期分隔线作为一条 `variant="system"` 的 `item` 承载居中灰条，
+ *   **标签文字（今天 / 昨天 / 某月某日）由 app 放进该项的 `content`，组件不算日期**。
+ * - **`autoScroll` 贴底 + 上滚暂停**：`items` 追加时若用户仍在底部则自动滚到底；用户手动上滚
+ *   离底即暂停自动贴底、滚回底部恢复。`autoScroll={false}` 整体关闭。
+ * - **`onReachTop` 只发信号、组件不 fetch**：滚到顶发一次 `onReachTop`，去哪取历史、怎么
+ *   prepend 全交 app；`loadingMore` 由 app 控制，为真时顶部显示转圈（复用 `<Loading>`）。组件
+ *   不拥有传输（接缝原则同 `ChatMessage`）。
+ * - **根节点 `role="log"` + 键盘可聚焦**：消息流作实时日志区（`aria-live="polite"` + 增量播报），
+ *   新消息由辅助技术增量读出；容器 `tabIndex={0}` 使纯键盘用户 Tab 进本区后用方向键 /
+ *   PageUp/Down 翻历史（滚到顶即触 `onReachTop`），聚焦环走 `:focus-visible`（WCAG 2.1.1）。
+ */
+export interface ChatListProps {
+    /** 消息数据（数据驱动，内部渲染 `ChatMessage`）；每项 = `ChatMessageProps` + `id` */
+    items: ChatListItem[];
+    /** 按 `variant` 的角色默认配置（照 Ant X `roles`）；合并进同 variant 的每项，item 显式值优先 */
+    roles?: Partial<Record<ChatMessageVariant, Partial<ChatMessageProps>>>;
+    /**
+     * 新消息自动贴底（照 Ant X `autoScroll`）：用户手动上滚时暂停、滚回底部恢复
+     * @default true
+     */
+    autoScroll?: boolean;
+    /**
+     * 滚到顶时触发（加载更多历史）：**组件不 fetch**，去哪拿数据、拿到怎么 prepend 全交 app；
+     * 组件只发信号并等 app 回灌 `items`（接缝原则同 `ChatMessage` 不拥有传输）
+     */
+    onReachTop?: () => void;
+    /**
+     * 顶部加载中（**由 app 控制**，配合 `onReachTop`）：为真在顶部显示转圈（复用 `<Loading>`）
+     * @default false
+     */
+    loadingMore?: boolean;
+    /** 自定义类名（挂到根容器） */
+    className?: string;
+    /** 行内样式（挂到根容器） */
+    style?: React.CSSProperties;
+}
+export declare const ChatList: React.FC<ChatListProps>;

package/dist/components/ChatList/ChatList.js

@@ -0,0 +1,49 @@
+import { ChatMessage as e } from "../ChatMessage/ChatMessage.js";
+import { Loading as t } from "../Loading/Loading.js";
+import n from "./chat-list.module.js";
+import { useCallback as r, useLayoutEffect as i, useRef as a } from "react";
+import o from "clsx";
+import { jsx as s, jsxs as c } from "react/jsx-runtime";
+//#region packages/react/src/components/ChatList/ChatList.tsx
+var l = 48, u = ({ items: u, roles: d, onReachTop: f, autoScroll: p = !0, loadingMore: m = !1, className: h, style: g }) => {
+	let _ = a(null), v = a(!1), y = a(!0), b = r(() => {
+		let e = _.current;
+		if (e == null) return;
+		let t = e.scrollHeight - e.clientHeight > l && e.scrollTop <= l;
+		t && !v.current && !m && f?.(), v.current = t;
+		let n = e.scrollHeight - e.clientHeight - e.scrollTop;
+		y.current = n <= l;
+	}, [f, m]);
+	return i(() => {
+		let e = _.current;
+		e == null || !p || !y.current || (e.scrollTop = e.scrollHeight);
+	}, [u, p]), /* @__PURE__ */ c("div", {
+		className: o(n.list, h),
+		style: g,
+		ref: _,
+		onScroll: b,
+		role: "log",
+		"aria-live": "polite",
+		"aria-relevant": "additions",
+		tabIndex: 0,
+		children: [m && /* @__PURE__ */ s("div", {
+			className: n["top-loader"],
+			children: /* @__PURE__ */ s(t, {
+				spinning: !0,
+				size: "small"
+			})
+		}), u.map((t, n) => {
+			let { id: r, ...i } = t, a = d?.[i.variant ?? "received"], o = a ? {
+				...a,
+				...i
+			} : i, c = u[n - 1], l = o.grouped ?? (c != null && c.variant === o.variant && o.variant !== "system");
+			return /* @__PURE__ */ s(e, {
+				...o,
+				grouped: l
+			}, r);
+		})]
+	});
+};
+u.displayName = "ChatList";
+//#endregion
+export { u as ChatList };

package/dist/components/ChatList/chat-list.module.js

@@ -0,0 +1,7 @@
+//#region packages/react/src/components/ChatList/chat-list.module.less
+var e = "_list_1xrm9_1", t = {
+	list: e,
+	"top-loader": "_top-loader_1xrm9_13"
+};
+//#endregion
+export { t as default, e as list };

package/dist/components/ChatList/index.d.ts

@@ -0,0 +1,2 @@
+export { ChatList } from './ChatList';
+export type { ChatListProps, ChatListItem } from './ChatList';

package/dist/components/ChatMessage/ChatMessage.d.ts

@@ -0,0 +1,52 @@
+import React from 'react';
+export type ChatMessageVariant = 'sent' | 'received' | 'system';
+export type ChatMessageStatus = 'sent' | 'delivered' | 'read';
+/**
+ * 单条聊天气泡：三态 `variant`（sent 右 / received 左 / system 居中灰条）+ `content`
+ * 消息体（纯文本或 ReactNode）+ `avatar`（复用 `<Avatar>`）+ `time` 时间元信息 +
+ * `status` 已读回执（仅 sent 侧）+ `grouped` 连发分组样式钩子。对外 props 照搬 Ant
+ * Design X `Bubble`（`content`/`variant`/`avatar`），已读回执 `status` 取 Ant 命名惯例。
+ *
+ * 跨-prop 注意事项：
+ * - **`variant` 驱动 placement**：sent 靠右、received 靠左、system 居中——不另立
+ *   `placement` prop（三态已定方位）。system 态无头像、无 status。
+ * - **`content` 优先，`children` 兜底**：两者皆可传消息体，`content` 存在时取 `content`。
+ * - **纯 emoji 自动大图无气泡**：`content`（或 `children`）为纯 emoji 字符串（≤3 个、无其它
+ *   可见字符）时自动渲成大图、去掉气泡底色与内边距（照即时通讯惯例），不需额外 prop。
+ * - **`status` 仅 sent 侧出现**：sent → 单勾、delivered → 双勾（均 `--stitch-text-muted`）、
+ *   read → 双勾 `--stitch-info`；勾走 `<Icon name="check">`（禁 emoji / Unicode `✓` / 裸
+ *   svg），回执整体挂 `role="img"` + 可访问名（已发送 / 已送达 / 已读），内层 Icon 纯装饰。
+ * - **`grouped` 只出样式钩子**：为真时隐藏头像、收紧下间距（相邻同 variant 连发），由上层
+ *   编排决定何时置真，组件本身不判断相邻。头像列占位随「该条是否带 `avatar`」：带头像的续条
+ *   （grouped 隐藏头像但保留列，同串气泡左缘对齐成一列，群聊）；无头像的消息不占列、气泡贴边
+ *   （1:1 私聊首尾条都无头像 → 整串贴边对齐）。要对齐成列 = 给每条都灌头像（列表走 `roles` /
+ *   每项 `avatar`），不靠「续条自动占空列」。
+ */
+export interface ChatMessageProps {
+    /**
+     * 气泡三态：sent（本方，右）/ received（对方，左）/ system（系统居中灰条）
+     * @default 'received'
+     */
+    variant?: ChatMessageVariant;
+    /** 消息内容（纯文本或 ReactNode）；纯 emoji 字符串自动大图无气泡。与 children 二选一（优先 content） */
+    content?: React.ReactNode;
+    /** 消息内容（content 的兜底写法） */
+    children?: React.ReactNode;
+    /** 头像（复用 `<Avatar>`）；system 态不显示 */
+    avatar?: React.ReactNode;
+    /** 时间 / 元信息（如发送时间） */
+    time?: React.ReactNode;
+    /** 已读回执：sent 单勾 / delivered 双勾 / read 双勾高亮；仅 sent 侧渲染 */
+    status?: ChatMessageStatus;
+    /**
+     * 连发分组样式钩子：为真时隐藏头像但保留头像列缩进（气泡对齐成列）、收紧下间距
+     * （相邻同 variant 时由上层置真）
+     * @default false
+     */
+    grouped?: boolean;
+    /** 自定义类名（挂到根容器） */
+    className?: string;
+    /** 行内样式（挂到根容器） */
+    style?: React.CSSProperties;
+}
+export declare const ChatMessage: React.FC<ChatMessageProps>;