@chenzy-design/svelte 0.3.0 → 0.4.1

package/dist/cascader/meta.js

@@ -5,7 +5,7 @@
 export const meta = {
     name: 'Cascader',
     category: 'input',
-    description: '级联选择器，点击逐级展开列，单选叶子节点。',
+    description: '级联选择器，点击（或 hover）逐级展开列，单选叶子/任一层级；支持 multiple 多选（每列 checkbox + 父子联动 + 多 tag 回显）、可搜索过滤（本地/远程 + 结果虚拟滚动）、动态加载子节点、自定义字段映射与触发器/结果渲染。',
     props: [
         { name: 'value', type: '(string|number)[] | (string|number)[][]', default: 'undefined', desc: '单选单条路径；多选多条路径' },
         { name: 'defaultValue', type: '(string|number)[] | (string|number)[][]', default: 'undefined' },
@@ -14,29 +14,78 @@ export const meta = {
         { name: 'defaultOpen', type: 'boolean', default: 'false' },
         { name: 'multiple', type: 'boolean', default: 'false', desc: '每列 checkbox 多选 + 父子联动，多 tag 回显' },
         { name: 'size', type: "'small'|'default'|'large'", default: 'default' },
-        { name: 'status', type: "'default'|'warning'|'error'", default: 'default' },
-        { name: 'placeholder', type: 'string', default: "'请选择'" },
+        { name: 'validateStatus', type: "'default'|'warning'|'error'", default: 'default', desc: '校验状态（对齐 Semi validateStatus）' },
+        { name: 'placeholder', type: 'string', default: 'undefined' },
         { name: 'disabled', type: 'boolean', default: 'false' },
-        { name: 'clearable', type: 'boolean', default: 'false' },
         { name: 'changeOnSelect', type: 'boolean', default: 'false', desc: '单选：点击任一层级（含中间非叶子）即提交该路径并触发 onChange，非叶子同时展开子列且不关闭面板，叶子提交并关闭；关闭时仅叶子提交并关闭' },
-        { name: 'expandTrigger', type: "'click'|'hover'", default: "'click'", desc: "'hover' 悬停非叶子节点即展开子级列" },
         { name: 'leafOnly', type: 'boolean', default: 'false', desc: '多选时完全勾选的父级折叠为父路径（只回传/计数到该父级）；默认 false 仅回传叶子' },
-        { name: 'filterable', type: 'boolean', default: 'false', desc: '可搜索（向后兼容别名，等价 filterTreeNode=true）' },
-        { name: 'filterTreeNode', type: 'boolean | ((query, path) => boolean)', default: 'undefined', desc: '是否可搜索及自定义匹配：false 关闭；true 默认 label 链子串匹配；函数自定义谓词。未传时回退 filterable' },
+        { name: 'filterTreeNode', type: 'boolean | ((query, path) => boolean)', default: 'undefined', desc: '是否可搜索及自定义匹配：false 关闭；true 默认 label 链子串匹配；函数自定义谓词' },
         { name: 'filterLeafOnly', type: 'boolean', default: 'true', desc: '搜索结果是否仅展示到叶子路径' },
         { name: 'displayProp', type: "'label'|'value'", default: "'label'", desc: '触发器回显使用的字段' },
         { name: 'separator', type: 'string', default: "' / '", desc: '路径分隔符（回显 + 搜索 label 链拼接）' },
         { name: 'maxTagCount', type: 'number', default: 'undefined', desc: '多选 Tag 溢出折叠阈值：超出显示前 N 个 + +M' },
         { name: 'emptyContent', type: 'string | Snippet', default: 'undefined', desc: '列为空时内容；缺省走 i18n' },
-        { name: 'destroyOnClose', type: 'boolean', default: 'false', desc: '关闭即卸载浮层内容（{#if}），重开重建；默认 false 首开后保留 DOM 仅隐藏' },
         { name: 'zIndex', type: 'number', default: '1030', desc: '浮层层级' },
         { name: 'getPopupContainer', type: '() => HTMLElement | null | undefined', default: 'undefined', desc: '浮层挂载容器，缺省 document.body；非 body 容器时 absolute 定位相对该容器' },
-        { name: 'columnWidth', type: 'number | number[]', default: '180', desc: '列宽：统一（number）或逐列（number[]，超出取末项）' },
         { name: 'loadData', type: '(node: CascaderNode) => Promise<CascaderNode[]>', default: 'undefined', desc: '动态加载子节点' },
         { name: 'displayRender', type: '(labels: string[], selectedNodes: CascaderNode[]) => string', default: 'undefined', desc: '自定义触发器选中路径回显（单选 + 多选每个 tag 共用）' },
         { name: 'onChange', type: '(value: (string|number)[] | (string|number)[][]) => void', default: 'undefined', desc: '单选回调单条路径；多选回调多条叶子路径' },
-        { name: 'onOpenChange', type: '(open: boolean) => void', default: 'undefined' },
-        { name: 'ariaLabel', type: 'string', default: 'undefined' },
+        { name: 'ariaLabel', type: 'string', default: "'Cascader'", desc: '可访问名（对齐 Semi aria-label）' },
+        { name: 'ariaLabelledby', type: 'string', default: 'undefined', desc: 'aria-labelledby：关联外部 label 元素（Form.Field 透传）' },
+        { name: 'ariaDescribedby', type: 'string', default: 'undefined', desc: 'aria-describedby：关联 helpText / extraText（Form.Field 透传）' },
+        { name: 'ariaErrormessage', type: 'string', default: 'undefined', desc: 'aria-errormessage：error 态关联错误信息容器（Form.Field 透传）' },
+        { name: 'ariaRequired', type: 'boolean', default: 'undefined', desc: 'aria-required：必填语义（Form.Field required 透传）' },
+        { name: 'borderless', type: 'boolean', default: 'false', desc: '无边框模式' },
+        { name: 'prefix', type: 'Snippet | string', default: 'undefined', desc: '前置内容' },
+        { name: 'insetLabel', type: 'Snippet | string', default: 'undefined', desc: '内嵌标签：触发器在值前渲染的标签（如「地区：」），Semi 中为 prefix 的别名' },
+        { name: 'insetLabelId', type: 'string', default: 'undefined', desc: '内嵌标签的 DOM id（供外部 aria-labelledby 引用）' },
+        { name: 'suffix', type: 'Snippet | string', default: 'undefined', desc: '后置内容' },
+        { name: 'clearIcon', type: 'Snippet', default: 'undefined', desc: '自定义清除图标' },
+        { name: 'expandIcon', type: 'Snippet', default: 'undefined', desc: '自定义菜单项右侧展开图标（列项 icon，对齐 Semi expandIcon）' },
+        { name: 'arrowIcon', type: 'Snippet', default: 'undefined', desc: '自定义触发器右侧下拉箭头（对齐 Semi arrowIcon，与 expandIcon 语义不同）' },
+        { name: 'motion', type: 'boolean', default: 'true', desc: '下拉框展开动画' },
+        { name: 'mouseEnterDelay', type: 'number', default: '50', desc: '鼠标移入延迟（ms）' },
+        { name: 'mouseLeaveDelay', type: 'number', default: '50', desc: '鼠标移出延迟（ms）' },
+        { name: 'autoAdjustOverflow', type: 'boolean', default: 'true', desc: '下拉框自动调整方向' },
+        { name: 'position', type: 'string', default: "'bottomStart'", desc: '下拉框方向' },
+        { name: 'style', type: 'string', default: 'undefined', desc: '选择框样式' },
+        { name: 'dropdownStyle', type: 'string | Record<string, string>', default: 'undefined', desc: '下拉菜单样式（合并进浮层根节点，不覆盖内置定位样式）' },
+        { name: 'dropdownClassName', type: 'string', default: 'undefined', desc: '追加到浮层根节点的自定义类名（与内置类名并存）' },
+        { name: 'dropdownMargin', type: 'number | { marginTop?: number; marginBottom?: number; marginLeft?: number; marginRight?: number }', default: 'undefined', desc: '浮层与 trigger 的额外间距（px）；数字映射到浮层 offset，对象取 marginTop' },
+        { name: 'onBlur', type: '(e: MouseEvent) => void', default: 'undefined', desc: '失焦回调' },
+        { name: 'onFocus', type: '(e: MouseEvent) => void', default: 'undefined', desc: '聚焦回调' },
+        { name: 'preventScroll', type: 'boolean', default: 'false', desc: '聚焦时阻止滚动' },
+        { name: 'stopPropagation', type: 'boolean', default: 'true', desc: '阻止下拉框点击冒泡' },
+        { name: 'topSlot', type: 'Snippet', default: 'undefined', desc: '面板顶部插槽' },
+        { name: 'bottomSlot', type: 'Snippet', default: 'undefined', desc: '面板底部插槽' },
+        { name: 'searchPosition', type: "'trigger'|'custom'", default: "'trigger'", desc: "搜索框位置：'trigger' 内置；'custom' 不渲染内置搜索框" },
+        { name: 'searchPlaceholder', type: 'string', default: 'undefined', desc: '搜索框占位文字' },
+        { name: 'treeNodeFilterProp', type: 'string', default: "'label'", desc: '搜索时过滤的属性' },
+        { name: 'filterRender', type: 'Snippet<[{ path: FlatPath }]>', default: 'undefined', desc: '自定义搜索结果项渲染' },
+        { name: 'filterSorter', type: '(a: FlatPath, b: FlatPath, input: string) => number', default: 'undefined', desc: '搜索结果自定义排序' },
+        { name: 'onSearch', type: '(value: string) => void', default: 'undefined', desc: '搜索输入回调' },
+        { name: 'remote', type: 'boolean', default: 'false', desc: '远程搜索模式：跳过本地过滤，只触发 onSearch' },
+        { name: 'virtualizeInSearch', type: '{ height: number; width: number; itemSize: number }', default: 'undefined', desc: '搜索结果虚拟滚动配置' },
+        { name: 'autoMergeValue', type: 'boolean', default: 'true', desc: '选中父节点时 value 不包含后代' },
+        { name: 'checkRelation', type: "'related'|'unRelated'", default: "'related'", desc: "勾选关系：'related' 父子联动；'unRelated' 独立" },
+        { name: 'onChangeWithObject', type: 'boolean', default: 'false', desc: 'onChange 回调是否返回完整 option 对象' },
+        { name: 'max', type: 'number', default: 'undefined', desc: '多选可勾选数量上限；超出时不选入并触发 onExceed（减少始终允许）' },
+        { name: 'onExceed', type: '(items: CascaderNode[]) => void', default: 'undefined', desc: '超出 max 时回调，传当前（含超出项）勾选的节点集合' },
+        { name: 'showRestTagsPopover', type: 'boolean', default: 'false', desc: '超出 maxTagCount 折叠的 tag 以 Popover 悬浮展示剩余项（hover +N）' },
+        { name: 'restTagsPopoverProps', type: 'Record<string, unknown>', default: 'undefined', desc: '传给剩余 tags Popover 的额外 props（透传，可覆盖默认）' },
+        { name: 'showClear', type: 'boolean', default: 'false', desc: '是否显示清除按钮（对齐 Semi showClear）' },
+        { name: 'keyMaps', type: '{ value?: string; label?: string; children?: string; disabled?: string; isLeaf?: string }', default: 'undefined', desc: '自定义字段名映射' },
+        { name: 'clickToSelect', type: 'boolean', default: 'false', desc: '点击任意节点即选中（含非叶子）' },
+        { name: 'enableLeafClick', type: 'boolean', default: 'false', desc: '多选模式下点击叶子节点触发勾选' },
+        { name: 'disableStrictly', type: 'boolean', default: 'false', desc: '禁用不从父节点继承（严格禁用）' },
+        { name: 'showNext', type: "'click'|'hover'", default: "'click'", desc: '展开触发方式（对齐 Semi showNext）：click 点击 / hover 悬停展开子列' },
+        { name: 'onClear', type: '() => void', default: 'undefined', desc: '清空回调' },
+        { name: 'onLoad', type: '(loadedKeys: Key[], data: CascaderNode) => void', default: 'undefined', desc: '异步加载完成回调' },
+        { name: 'onSelect', type: '(value: Key) => void', default: 'undefined', desc: '节点选中回调（单选叶子选中时）' },
+        { name: 'onDropdownVisibleChange', type: '(visible: boolean) => void', default: 'undefined', desc: '下拉面板显隐回调' },
+        { name: 'onListScroll', type: '(e: Event, info: { panelIndex: number; activeNode: CascaderNode | null }) => void', default: 'undefined', desc: '列滚动回调' },
+        { name: 'triggerRender', type: 'Snippet<[{ value: Key[] | Key[][] | undefined; placeholder: string; isOpen: boolean; disabled: boolean }]>', default: 'undefined', desc: '完全自定义触发器渲染' },
+        { name: 'class', type: 'string', default: "''", desc: '根节点自定义类名（对齐 Semi className）' },
     ],
     a11y: {
         role: 'combobox',
@@ -48,8 +97,32 @@ export const meta = {
         ],
     },
     tokens: [
+        // 触发器复用 Input/Select 填充式 token（背景/描边/圆角/内边距/状态描边）
         '--cd-select-*',
-        '--cd-tree-*',
+        '--cd-input-*',
+        // 菜单节点尺寸复用 Tree（节点高度/内边距）
+        '--cd-tree-node-height',
+        '--cd-tree-node-padding-x',
+        // Cascader 专属 token（对齐 Semi cascader/variables.scss）
+        '--cd-color-cascader-option-bg-hover',
+        '--cd-color-cascader-option-bg-active',
+        '--cd-color-cascader-option-bg-selected',
+        '--cd-color-cascader-option-main-text-default',
+        '--cd-color-cascader-option-disabled-text-default',
+        '--cd-color-cascader-option-empty-text-default',
+        '--cd-color-cascader-option-icon-default',
+        '--cd-color-cascader-icon-default',
+        '--cd-color-cascader-icon-hover',
+        '--cd-color-cascader-icon-active',
+        '--cd-color-cascader-prefix-suffix-text-default',
+        '--cd-color-cascader-selection-n-text-default',
+        '--cd-color-cascader-selection-text-default',
+        '--cd-color-cascader-placeholder-text-default',
+        // insetLabel 内嵌标签消费的 label token
+        '--cd-color-cascader-label-text-default',
+        '--cd-font-cascader-label-fontweight',
+        '--cd-font-cascader-select-fontweight',
+        '--cd-color-cascader-select-highlight',
         '--cd-cascader-column-width',
         '--cd-cascader-column-border',
         '--cd-focus-ring',

package/dist/chat/Chat.svelte

@@ -0,0 +1,483 @@
+<!--
+  Chat — 对话主容器（对齐 Semi Chat）。
+  消息列表滚动区（role=log）+ back-bottom 悬浮按钮（core.shouldShowBackBottom + SHOW_SCROLL_GAP）
+  + 输入区（InputBox）+ 提示区（Hint）+ topSlot / bottomSlot。
+  受控/非受控 chats（对齐 Upload 的 value 模式）：所有 chats 变换（发送/删除/赞/踩/重生成/
+  清除上下文）经 core 纯函数产出新数组，经 onChatsChange 回传；非受控时内部 inner 承载。
+
+  滚动红线：$effect 只监听容器 scroll → 写专用 backBottomVisible state；不在 effect 里回读派生量做二次 set，
+  避免自循环。scrollToBottom 命令式（rAF / 动画），不在 render 期触发。
+
+  ref 方法（export function）：resetMessage / scrollToBottom(animation) / clearContext / sendMessage。
+  全 token，类名前缀 cd-。
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { untrack } from 'svelte';
+  import {
+    CHAT_ALIGN,
+    CHAT_MODE,
+    SHOW_SCROLL_GAP,
+    SCROLL_ANIMATION_TIME,
+    shouldShowBackBottom,
+    resolveEnableUpload,
+    buildSendContent,
+    appendDivider,
+    makeUserMessage,
+    deleteMessageFrom,
+    toggleLike,
+    toggleDislike,
+    resetLastMessage,
+    type Message,
+    type RoleConfig,
+    type ChatAttachment,
+    type ChatAlign,
+    type ChatMode,
+    type SendHotKey,
+    type EnableUploadProps,
+  } from '@chenzy-design/core';
+  import { IconChevronDown, IconDisc } from '@chenzy-design/icons';
+  import { useLocale } from '../locale-provider/index.js';
+  import type { UploadFileItem } from '../upload/types.js';
+  import Button from '../button/Button.svelte';
+  import ChatBox from './ChatBox.svelte';
+  import InputBox from './InputBox.svelte';
+  import Hint from './Hint.svelte';
+  import type {
+    RenderInputAreaProps,
+    RenderAvatarProps,
+    RenderTitleProps,
+    RenderContentProps,
+    RenderActionProps,
+    RenderFullChatBoxProps,
+    RenderHintBoxProps,
+  } from './types.js';
+
+  interface Props {
+    /** 消息列表。 */
+    chats?: Message[];
+    /** 角色配置（名称/头像/色）。 */
+    roleConfig?: RoleConfig;
+    /** 布局对齐。 */
+    align?: ChatAlign;
+    /** 气泡模式。 */
+    mode?: ChatMode;
+    /** 发送快捷键。 */
+    sendHotKey?: SendHotKey;
+    /** 是否展示清除上下文按钮。 */
+    showClearContext?: boolean;
+    /** 是否展示停止生成按钮。 */
+    showStopGenerate?: boolean;
+    /**
+     * 是否可以发送（对齐 Semi canSend）。未设置时由输入内容 / 附件推断；
+     * 显式设置时以此为准。
+     */
+    canSend?: boolean | undefined;
+    /** 提示项列表。 */
+    hints?: string[];
+    /** 上传能力（true/false 或三态对象）。 */
+    enableUpload?: boolean | EnableUploadProps;
+    /** 透传内部 Upload 的 props。 */
+    uploadProps?: Record<string, unknown>;
+    /** 上传按钮 Tooltip 提示（对齐 Semi uploadTipProps）；传对象则用 Tooltip 包裹上传触发器。 */
+    uploadTipProps?: Record<string, unknown>;
+    /** 透传 MarkdownRender props。 */
+    markdownRenderProps?: Record<string, unknown>;
+    /** 输入框占位。 */
+    placeholder?: string;
+    /** 顶部插槽。 */
+    topSlot?: Snippet;
+    /** 底部插槽（列表与输入区之间）。 */
+    bottomSlot?: Snippet;
+    /** 附加类名。 */
+    class?: string;
+    /** 内联样式。 */
+    style?: string;
+    // 回调
+    onChatsChange?: (chats: Message[]) => void;
+    onMessageSend?: (content: string, attachment: UploadFileItem[]) => void;
+    onInputChange?: (props: { value: string; attachment: UploadFileItem[] }) => void;
+    onClear?: () => void;
+    onHintClick?: (hint: string) => void;
+    onStopGenerator?: () => void;
+    onMessageCopy?: (message: Message) => void;
+    onMessageDelete?: (message: Message) => void;
+    onMessageReset?: (message: Message) => void;
+    onMessageGoodFeedback?: (message: Message) => void;
+    onMessageBadFeedback?: (message: Message) => void;
+    // 自定义渲染 snippet
+    renderInputArea?: Snippet<[RenderInputAreaProps]>;
+    renderChatBoxAvatar?: Snippet<[RenderAvatarProps]>;
+    renderChatBoxTitle?: Snippet<[RenderTitleProps]>;
+    renderChatBoxContent?: Snippet<[RenderContentProps]>;
+    renderChatBoxAction?: Snippet<[RenderActionProps]>;
+    renderFullChatBox?: Snippet<[RenderFullChatBoxProps]>;
+    renderHintBox?: Snippet<[RenderHintBoxProps]>;
+    renderDivider?: Snippet<[Message]>;
+  }
+
+  let {
+    chats,
+    roleConfig,
+    align = CHAT_ALIGN.LEFT_RIGHT,
+    mode = CHAT_MODE.BUBBLE,
+    sendHotKey = 'enter',
+    showClearContext = false,
+    showStopGenerate = false,
+    canSend,
+    hints,
+    enableUpload = true,
+    uploadProps,
+    uploadTipProps,
+    markdownRenderProps,
+    placeholder,
+    topSlot,
+    bottomSlot,
+    class: className = '',
+    style,
+    onChatsChange,
+    onMessageSend,
+    onInputChange,
+    onClear,
+    onHintClick,
+    onStopGenerator,
+    onMessageCopy,
+    onMessageDelete,
+    onMessageReset,
+    onMessageGoodFeedback,
+    onMessageBadFeedback,
+    renderInputArea,
+    renderChatBoxAvatar,
+    renderChatBoxTitle,
+    renderChatBoxContent,
+    renderChatBoxAction,
+    renderFullChatBox,
+    renderHintBox,
+    renderDivider,
+  }: Props = $props();
+
+  const loc = useLocale();
+
+  // 受控（传了 chats）/ 非受控（内部 inner）——对齐 Upload 的 value 模式。
+  // 受控：父级拥有 chats，我们只经 onChatsChange 回传、从不写 prop；
+  // 非受控：内部 inner 承载，commitChats 同步写入并回传。
+  const isControlled = $derived(chats !== undefined);
+  // 非受控初始为空；受控（传了 chats）时 inner 不参与渲染。
+  let inner = $state<Message[]>([]);
+  const currentChats = $derived(isControlled ? (chats ?? []) : inner);
+
+  const uploadModes = $derived(resolveEnableUpload(enableUpload));
+
+  // back-bottom 显隐：专用 state，仅 scroll / resize 事件命令式写入（红线：不在 effect 回读派生做二次 set）。
+  let backBottomVisible = $state(false);
+  let containerEl: HTMLDivElement | null = $state(null);
+
+  let idSeq = 0;
+  function makeId(): string {
+    idSeq += 1;
+    return `cd-chat-${Date.now()}-${idSeq}`;
+  }
+
+  function commitChats(next: Message[]): void {
+    // 非受控时写内部 inner；受控时由父级据 onChatsChange 更新 chats（我们不写 prop）。
+    if (!isControlled) inner = next;
+    onChatsChange?.(next);
+  }
+
+  function updateBackBottom(): void {
+    const el = containerEl;
+    if (!el) return;
+    backBottomVisible = shouldShowBackBottom(
+      el.scrollHeight,
+      el.scrollTop,
+      el.clientHeight,
+      SHOW_SCROLL_GAP,
+    );
+  }
+
+  function handleScroll(): void {
+    // rAF 对齐 Semi containerScroll（读布局在下一帧，避免与写抖动）。
+    requestAnimationFrame(updateBackBottom);
+  }
+
+  function scrollToBottomImmediately(): void {
+    const el = containerEl;
+    if (el) el.scrollTop = el.scrollHeight;
+  }
+
+  function scrollToBottomWithAnimation(): void {
+    const el = containerEl;
+    if (!el) return;
+    const from = el.scrollTop;
+    const to = el.scrollHeight;
+    const start = performance.now();
+    const step = (now: number): void => {
+      const t = Math.min(1, (now - start) / SCROLL_ANIMATION_TIME);
+      // easeInOutCubic（对齐 Semi 动画曲线）。
+      const eased = t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+      el.scrollTop = from + (to - from) * eased;
+      if (t < 1) requestAnimationFrame(step);
+    };
+    requestAnimationFrame(step);
+  }
+
+  // 新消息后滚到底（列表长度变化时命令式触发）。lastLen 是非响应式簿记（untrack 读，
+  // 只依赖 currentChats.length），避免自身进依赖图导致 effect 自循环。
+  let lastLen = 0;
+  $effect(() => {
+    const len = currentChats.length;
+    if (len !== untrack(() => lastLen)) {
+      lastLen = len;
+      requestAnimationFrame(() => {
+        scrollToBottomImmediately();
+        updateBackBottom();
+      });
+    }
+  });
+
+  // UploadFileItem → core ChatAttachment（file→fileInstance，供 core MIME/后缀图片分流判定）。
+  // exactOptionalPropertyTypes：仅在有值时写入可选字段，不显式赋 undefined。
+  function toAttachments(list: UploadFileItem[]): ChatAttachment[] {
+    return list.map((item) => {
+      const att: ChatAttachment = {
+        uid: item.uid,
+        name: item.name,
+        size: item.size,
+        status: item.status,
+      };
+      if (item.url !== undefined) att.url = item.url;
+      if (item.file !== undefined) att.fileInstance = item.file;
+      return att;
+    });
+  }
+
+  // 发送：core.buildSendContent 组装 → makeUserMessage 追加 → 回传 + notify。
+  function doSend(content: string, attachment: UploadFileItem[]): void {
+    const built = buildSendContent(content, toAttachments(attachment));
+    const message = makeUserMessage(built, makeId);
+    commitChats([...currentChats, message]);
+    onMessageSend?.(content, attachment);
+  }
+
+  function doClearContext(): void {
+    commitChats(appendDivider(currentChats, makeId));
+    onClear?.();
+  }
+
+  function doHintClick(hint: string): void {
+    const message = makeUserMessage(hint, makeId);
+    commitChats([...currentChats, message]);
+    onHintClick?.(hint);
+  }
+
+  function doDelete(message: Message): void {
+    onMessageDelete?.(message);
+    commitChats(deleteMessageFrom(currentChats, message));
+  }
+
+  function doLike(message: Message): void {
+    onMessageGoodFeedback?.(message);
+    commitChats(toggleLike(currentChats, message));
+  }
+
+  function doDislike(message: Message): void {
+    onMessageBadFeedback?.(message);
+    commitChats(toggleDislike(currentChats, message));
+  }
+
+  function doReset(message: Message): void {
+    commitChats(resetLastMessage(currentChats, makeId));
+    onMessageReset?.(message);
+  }
+
+  function roleOf(message: Message) {
+    const key = typeof message.role === 'string' ? message.role : '';
+    return roleConfig?.[key];
+  }
+
+  // ---- ref 方法（对齐 Semi ChatFoundation 暴露的命令式 API） ----
+  /** 重置最后一条消息为 loading（对齐 Semi resetMessage）。 */
+  export function resetMessage(): void {
+    const last = currentChats[currentChats.length - 1];
+    commitChats(resetLastMessage(currentChats, makeId));
+    if (last) onMessageReset?.(last);
+  }
+  /** 滚动到底部；animation=true 时带动画。 */
+  export function scrollToBottom(animation = false): void {
+    if (animation) scrollToBottomWithAnimation();
+    else scrollToBottomImmediately();
+  }
+  /** 清除上下文（追加 divider）。 */
+  export function clearContext(): void {
+    doClearContext();
+  }
+  /** 以文本 + 附件发送一条消息。 */
+  export function sendMessage(content: string, attachment: UploadFileItem[] = []): void {
+    doSend(content, attachment);
+  }
+</script>
+
+<!-- DOM 对齐 Semi：.cd-chat > .cd-chat-inner > .cd-chat-content > .cd-chat-container；
+     -action 容器承载 backBottom/stop（Button + 具名图标）。 -->
+<div class="cd-chat {className}" {style}>
+  <div class="cd-chat-inner">
+    {#if topSlot}
+      <div class="cd-chat-topSlot">{@render topSlot()}</div>
+    {/if}
+
+    <div class="cd-chat-content">
+      <div
+        bind:this={containerEl}
+        class="cd-chat-container"
+        role="log"
+        aria-live="polite"
+        aria-label={loc().t('Chat.messageList')}
+        onscroll={handleScroll}
+      >
+        {#each currentChats as message, i (message.id ?? i)}
+          <ChatBox
+            {message}
+            role={roleOf(message)}
+            {align}
+            {mode}
+            lastChat={i === currentChats.length - 1}
+            {markdownRenderProps}
+            onMessageCopy={(m) => onMessageCopy?.(m)}
+            onMessageDelete={doDelete}
+            onMessageReset={doReset}
+            onMessageGoodFeedback={doLike}
+            onMessageBadFeedback={doDislike}
+            {renderChatBoxAvatar}
+            {renderChatBoxTitle}
+            {renderChatBoxContent}
+            {renderChatBoxAction}
+            {renderFullChatBox}
+            {renderDivider}
+          />
+        {/each}
+      </div>
+
+      <!-- 回到底部 / 停止生成悬浮按钮（对齐 Semi -action，Button + 具名图标） -->
+      <div class="cd-chat-action">
+        {#if backBottomVisible && !showStopGenerate}
+          <Button
+            class="cd-chat-action-content cd-chat-action-backBottom"
+            theme="light"
+            type="tertiary"
+            onclick={() => scrollToBottom(true)}
+            ariaLabel={loc().t('Chat.backToBottom')}
+            title={loc().t('Chat.backToBottom')}
+            icon={backBottomIcon}
+          />
+        {/if}
+        {#if showStopGenerate}
+          <Button
+            class="cd-chat-action-content cd-chat-action-stop"
+            theme="light"
+            type="tertiary"
+            onclick={() => onStopGenerator?.()}
+            icon={stopIcon}
+          >
+            {loc().t('Chat.stop')}
+          </Button>
+        {/if}
+      </div>
+    </div>
+
+    {#if bottomSlot}
+      <div class="cd-chat-bottomSlot">{@render bottomSlot()}</div>
+    {/if}
+
+    {#if hints && hints.length > 0}
+      <Hint {hints} onHintClick={doHintClick} {renderHintBox} />
+    {/if}
+
+    <InputBox
+      {sendHotKey}
+      {placeholder}
+      {showClearContext}
+      {canSend}
+      clickUpload={uploadModes.clickUpload}
+      pasteUpload={uploadModes.pasteUpload}
+      dragUpload={uploadModes.dragUpload}
+      {uploadProps}
+      {uploadTipProps}
+      onSend={doSend}
+      onClearContext={doClearContext}
+      onInputChange={(p) => onInputChange?.(p)}
+      {renderInputArea}
+    />
+  </div>
+</div>
+
+{#snippet backBottomIcon()}<IconChevronDown />{/snippet}
+{#snippet stopIcon()}<IconDisc />{/snippet}
+
+<style>
+  /* —— 根（对齐 Semi .semi-chat：paddingY + max-width + flex column） —— */
+  .cd-chat {
+    padding-top: var(--cd-chat-paddingY);
+    padding-bottom: var(--cd-chat-paddingY);
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+    max-width: var(--cd-chat-max-width);
+    position: relative;
+    overflow: hidden;
+  }
+
+  .cd-chat-inner {
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+  }
+
+  /* —— 内容滚动区（对齐 Semi -content > -container） —— */
+  .cd-chat-content {
+    overflow: hidden;
+    flex: 1 1;
+    position: relative;
+  }
+
+  .cd-chat-container {
+    padding-left: var(--cd-chat-container-paddingX);
+    padding-right: var(--cd-chat-container-paddingX);
+    height: 100%;
+    overflow: auto;
+  }
+
+  /* —— 回到底部 / 停止生成（对齐 Semi -action，绝对定位居中底部） —— */
+  .cd-chat-action {
+    position: relative;
+    z-index: var(--cd-chat-action-z);
+  }
+  .cd-chat-action :global(.cd-chat-action-content) {
+    position: absolute;
+    bottom: var(--cd-chat-action-content-bottom);
+    left: 50%;
+    transform: translateX(-50%);
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    background: var(--cd-chat-action-content-bg);
+    border: var(--cd-chat-action-content-border-width) solid var(--cd-chat-action-content-border);
+  }
+  .cd-chat-action :global(.cd-chat-action-content:hover) {
+    background: var(--cd-chat-action-content-bg-hover);
+  }
+  .cd-chat-action :global(.cd-chat-action-backBottom) {
+    width: var(--cd-chat-backBottom-wrapper-width);
+    height: var(--cd-chat-backBottom-wrapper-width);
+    border-radius: 50%;
+  }
+  .cd-chat-action :global(.cd-chat-action-stop) {
+    user-select: none;
+    height: var(--cd-chat-action-stop-height);
+    border-radius: calc(var(--cd-chat-action-stop-height) / 2);
+  }
+
+  .cd-chat-topSlot,
+  .cd-chat-bottomSlot {
+    flex: 0 0 auto;
+  }
+</style>