iter: d10 toast 手动关闭 + 堆叠上限

.ua/backlog.json

@@ -128,6 +128,14 @@
       "acceptance": "新增 slider.ts：value 信号双向绑定（拖动写回 + 外部赋值同步），min/max/step 可配，disabled 支持布尔或信号，showValue 可关，onChange 回调；样式只消费 --ua-* 令牌（accent-color）且带聚焦光环与禁用态；导出 / manifest / 文档 / llms-full.txt / demo 同步；npm run check 全绿",
       "status": "done",
       "notes": "组件不持有数值，一律委托调用方信号；effect 内等值不重写 input.value，避免拖动过程被打断；轨道配色用 accent-color 令牌化，无需自绘 thumb；demo 新增 sec-slider（音量 step 5 + 与 locked 信号联动的禁用滑块）"
+    },
+    {
+      "id": "d10",
+      "title": "toast 补手动关闭与同屏堆叠上限",
+      "motivation": "自动消失前用户无法提前关掉（如已看清错误），且连续触发会无限堆叠淹没页面",
+      "acceptance": "ToastProps 新增 closable（显示 × 立即退场）；同屏最多 4 条，超出挤掉最早一条；退场逻辑抽为内部 dismiss() 供自动/手动共用；is-closable 才接收指针事件，其余保持 pointer-events:none；manifest/文档/llms-full.txt/demo 同步；npm run check 全绿",
+      "status": "done",
+      "notes": "dismiss() 统一 transitionend + 320ms 双保险；超限用 firstElementChild.remove() 立即腾位（不走动画，保证硬上限）；demo sec-toast 增加「可关闭」按钮演示 showToast({closable:true})"
     }
   ]
 }

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-23T08:53:00.281Z",
+  "generatedAt": "2026-10-23T08:53:43.712Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -156,7 +156,7 @@
           "card(props, ...children)：卡片容器",
           "badge(props)：徽标，variant = default | success | warning | danger",
           "alert(props)：提示条，variant = info | success | warning | danger",
-          "toast.info/success/warning/error(message, duration?)：消息提示工厂，右上角堆叠，默认 3s 自动消失，出入场微动画；showToast(props) 为完整入参版本",
+          "toast.info/success/warning/error(message, duration?)：消息提示工厂，右上角堆叠，默认 3s 自动消失，出入场微动画；showToast(props) 为完整入参版本（closable 显示关闭按钮，同屏最多 4 条）",
           "tooltip(props, trigger)：悬浮提示，包裹触发器，hover / focus 延迟 150ms 出场，移出 / 失焦 / Esc 收起",
           "popover(props, trigger)：可交互气泡卡片，包裹触发器，默认点击开合 + 点外部 / Esc 收起，content 可放按钮等交互元素",
           "skeleton(props)：骨架屏占位，variant = text | rect | circle，text 支持 rows 多行，扫光微动画",
@@ -762,6 +762,12 @@
                 "d": "自动消失毫秒；缺省 3000",
                 "df": "3000"
               },
+              {
+                "n": "closable",
+                "t": "boolean",
+                "d": "显示关闭按钮，点 × 立即收起；缺省 false（仅可关闭的 toast 接收指针事件，其余保持穿透）",
+                "df": "false"
+              },
               {
                 "n": "variant",
                 "t": "'info' | 'success' | 'warning' | 'danger'",
@@ -774,7 +780,8 @@
               "直接调用语义工厂：toast.info / success / warning / error(message, duration?)，无需先建容器",
               "不传 duration 时默认停留 3 秒后自动淡出并移除节点",
               "多条消息在右上角自动纵向堆叠，互不遮挡",
-              "需要完整入参（含 variant）时用 showToast(props)；组件挂载容器由内部懒创建，样式随 ui.css 一起引入"
+              "需要完整入参（含 variant）时用 showToast(props)；组件挂载容器由内部懒创建，样式随 ui.css 一起引入",
+              "同屏最多 4 条，超出自动挤掉最早一条；需要用户主动确认的消息用 showToast({ closable: true }) 给个 ×"
             ]
           },
           {

.ua/iterations.log

@@ -14,3 +14,4 @@
 {"time": "2026-10-23T16:51:48+08:00", "id": "d07", "result": "done", "summary": "新增可交互气泡卡片 popover：点击/hover 触发、点外部与 Esc 收起、内容可交互且内部点击不误关；manifest/llms/demo 同步，check 全绿"}
 {"time": "2026-10-23T16:52:28+08:00", "id": "d08", "result": "done", "summary": "演示页改双栏 shell：sticky 侧边目录由 .sec 自动反推 + IntersectionObserver 滚动高亮，窄屏隐藏、reduced-motion 关平滑滚动；check 全绿"}
 {"time": "2026-10-23T16:53:06+08:00", "id": "d09", "result": "done", "summary": "新增滑块 slider：value 信号双向绑定 + min/max/step + 布尔|信号禁用 + showValue，原生 range 承载键盘与触屏，accent-color 令牌化；manifest/llms/demo 同步，check 全绿"}
+{"time": "2026-10-23T16:53:44+08:00", "id": "d10", "result": "done", "summary": "toast 新增 closable（× 手动关闭）与同屏上限 4 条，退场统一走 dismiss() 双兜底；is-closable 才接收指针；demo/manifest/llms 同步，check 全绿"}

apps/demo/main.ts

@@ -17,6 +17,7 @@ import {
   progress,
   radioGroup,
   select,
+  showToast,
   skeleton,
   slider,
   spinner,
@@ -206,6 +207,7 @@ const content = h(
       button({ label: '错误', variant: 'danger', onClick: () => toast.error('网络请求失败') }),
       button({ label: '警告', onClick: () => toast.warning('磁盘空间不足') }),
       button({ label: '信息（1.5s）', onClick: () => toast.info('已同步云端', 1500) }),
+      button({ label: '可关闭', variant: 'ghost', onClick: () => showToast({ message: '这条可以手动关掉', variant: 'warning', closable: true }) }),
     ),
   ),
   section(

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-23T08:53:00.281Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-23T08:53:43.712Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -400,6 +400,7 @@ skeleton({ variant: 'text', rows: 3 }); skeleton({ variant: 'circle' }); skeleto
 
 - message（必填）：string —— 提示文案
 - duration（默认 3000）：number —— 自动消失毫秒；缺省 3000
+- closable（默认 false）：boolean —— 显示关闭按钮，点 × 立即收起；缺省 false（仅可关闭的 toast 接收指针事件，其余保持穿透）
 - variant（默认 info）：'info' | 'success' | 'warning' | 'danger' —— 语义色；缺省 info（toast.error 对应 danger）
 
 示例：
@@ -414,6 +415,7 @@ toast.success('保存成功'); toast.error('网络请求失败', 5000)
 2. 不传 duration 时默认停留 3 秒后自动淡出并移除节点
 3. 多条消息在右上角自动纵向堆叠，互不遮挡
 4. 需要完整入参（含 variant）时用 showToast(props)；组件挂载容器由内部懒创建，样式随 ui.css 一起引入
+5. 同屏最多 4 条，超出自动挤掉最早一条；需要用户主动确认的消息用 showToast({ closable: true }) 给个 ×
 
 现场演示：apps/docs/demo.html#sec-toast
 
@@ -663,7 +665,7 @@ API 速览：
 - card(props, ...children)：卡片容器
 - badge(props)：徽标，variant = default | success | warning | danger
 - alert(props)：提示条，variant = info | success | warning | danger
-- toast.info/success/warning/error(message, duration?)：消息提示工厂，右上角堆叠，默认 3s 自动消失，出入场微动画；showToast(props) 为完整入参版本
+- toast.info/success/warning/error(message, duration?)：消息提示工厂，右上角堆叠，默认 3s 自动消失，出入场微动画；showToast(props) 为完整入参版本（closable 显示关闭按钮，同屏最多 4 条）
 - tooltip(props, trigger)：悬浮提示，包裹触发器，hover / focus 延迟 150ms 出场，移出 / 失焦 / Esc 收起
 - popover(props, trigger)：可交互气泡卡片，包裹触发器，默认点击开合 + 点外部 / Esc 收起，content 可放按钮等交互元素
 - skeleton(props)：骨架屏占位，variant = text | rect | circle，text 支持 rows 多行，扫光微动画

llms.txt

@@ -61,7 +61,7 @@
   - card(props, ...children)：卡片容器
   - badge(props)：徽标，variant = default | success | warning | danger
   - alert(props)：提示条，variant = info | success | warning | danger
-  - toast.info/success/warning/error(message, duration?)：消息提示工厂，右上角堆叠，默认 3s 自动消失，出入场微动画；showToast(props) 为完整入参版本
+  - toast.info/success/warning/error(message, duration?)：消息提示工厂，右上角堆叠，默认 3s 自动消失，出入场微动画；showToast(props) 为完整入参版本（closable 显示关闭按钮，同屏最多 4 条）
   - tooltip(props, trigger)：悬浮提示，包裹触发器，hover / focus 延迟 150ms 出场，移出 / 失焦 / Esc 收起
   - popover(props, trigger)：可交互气泡卡片，包裹触发器，默认点击开合 + 点外部 / Esc 收起，content 可放按钮等交互元素
   - skeleton(props)：骨架屏占位，variant = text | rect | circle，text 支持 rows 多行，扫光微动画

packages/skin/ui/src/toast.ts

@@ -3,6 +3,7 @@ import type { ToastProps } from './types.js';
 
 let host: HTMLElement | null = null; // 全局右上角堆叠容器：首条消息出现时懒创建
 let seq = 0; // 自增序号：为每条 toast 生成唯一 id，辅助无障碍定位
+const MAX_STACK = 4; // 同屏最多条数：超出即挤掉最早一条，避免刷屏淹页面
 
 /*** 确保堆叠容器存在：fixed 挂在 body 末尾，后续消息依次向上堆叠 ***/
 function ensureHost(): HTMLElement {
@@ -12,19 +13,29 @@ function ensureHost(): HTMLElement {
   return host;
 }
 
+/*** 退场并移除：先摘 ua-open 触发过渡，transitionend 与 320ms 超时兜底二选一 ***/
+function dismiss(item: HTMLElement): void {
+  item.classList.remove('ua-open');
+  item.addEventListener('transitionend', () => item.remove(), { once: true });
+  window.setTimeout(() => item.isConnected && item.remove(), 320); // reduced-motion 下 transition 不触发
+}
+
 /*** 弹出一条 toast：语义色由 variant 决定，duration 毫秒后自动淡出并移除节点 ***/
 export function showToast(props: ToastProps): HTMLElement {
   // —— 状态集中声明 ——
-  const item = h('div', { class: `ua-toast ua-toast-${props.variant ?? 'info'}`, role: 'status', id: `ua-toast-${++seq}` }, props.message);
   const duration = props.duration ?? 3000; // 停留时长毫秒
+  const item = h(
+    'div',
+    { class: `ua-toast ua-toast-${props.variant ?? 'info'}${props.closable ? ' is-closable' : ''}`, role: 'status', id: `ua-toast-${++seq}` },
+    h('span', { class: 'ua-toast-msg' }, props.message),
+    props.closable ? h('button', { type: 'button', class: 'ua-toast-close', 'aria-label': '关闭提示', onClick: () => dismiss(item) }, '×') : null,
+  );
+  const stack = ensureHost();
+  if (stack.childElementCount >= MAX_STACK) stack.firstElementChild?.remove(); // 超过上限直接挤掉最早一条
 
-  ensureHost().appendChild(item);
+  stack.appendChild(item);
   requestAnimationFrame(() => item.classList.add('ua-open')); // 下一帧入场，保证过渡生效
-  window.setTimeout(() => {
+  window.setTimeout(() => dismiss(item), duration);
-    item.classList.remove('ua-open'); // 先退场再摘除，退场动画与 reduced-motion 兜底都安全
-    item.addEventListener('transitionend', () => item.remove(), { once: true });
-    window.setTimeout(() => item.isConnected && item.remove(), 320); // transition 不触发时的兜底移除
-  }, duration);
   return item;
 }
 

packages/skin/ui/src/types.ts

@@ -187,6 +187,7 @@ export interface PaginationProps {
 export interface ToastProps {
   message: string;  // 提示文案
   duration?: number; // 自动消失毫秒；缺省 3000
+  closable?: boolean; // 是否显示关闭按钮（手动立即收起）；缺省 false
   variant?: 'info' | 'success' | 'warning' | 'danger'; // 语义色；缺省 info
 }
 

packages/skin/ui/ua.manifest.json

@@ -27,7 +27,7 @@
       "card(props, ...children)：卡片容器",
       "badge(props)：徽标，variant = default | success | warning | danger",
       "alert(props)：提示条，variant = info | success | warning | danger",
-      "toast.info/success/warning/error(message, duration?)：消息提示工厂，右上角堆叠，默认 3s 自动消失，出入场微动画；showToast(props) 为完整入参版本",
+      "toast.info/success/warning/error(message, duration?)：消息提示工厂，右上角堆叠，默认 3s 自动消失，出入场微动画；showToast(props) 为完整入参版本（closable 显示关闭按钮，同屏最多 4 条）",
       "tooltip(props, trigger)：悬浮提示，包裹触发器，hover / focus 延迟 150ms 出场，移出 / 失焦 / Esc 收起",
       "popover(props, trigger)：可交互气泡卡片，包裹触发器，默认点击开合 + 点外部 / Esc 收起，content 可放按钮等交互元素",
       "skeleton(props)：骨架屏占位，variant = text | rect | circle，text 支持 rows 多行，扫光微动画",
@@ -633,6 +633,12 @@
             "d": "自动消失毫秒；缺省 3000",
             "df": "3000"
           },
+          {
+            "n": "closable",
+            "t": "boolean",
+            "d": "显示关闭按钮，点 × 立即收起；缺省 false（仅可关闭的 toast 接收指针事件，其余保持穿透）",
+            "df": "false"
+          },
           {
             "n": "variant",
             "t": "'info' | 'success' | 'warning' | 'danger'",
@@ -645,7 +651,8 @@
           "直接调用语义工厂：toast.info / success / warning / error(message, duration?)，无需先建容器",
           "不传 duration 时默认停留 3 秒后自动淡出并移除节点",
           "多条消息在右上角自动纵向堆叠，互不遮挡",
-          "需要完整入参（含 variant）时用 showToast(props)；组件挂载容器由内部懒创建，样式随 ui.css 一起引入"
+          "需要完整入参（含 variant）时用 showToast(props)；组件挂载容器由内部懒创建，样式随 ui.css 一起引入",
+          "同屏最多 4 条，超出自动挤掉最早一条；需要用户主动确认的消息用 showToast({ closable: true }) 给个 ×"
         ]
       },
       {

packages/skin/ui/ui.css

@@ -741,6 +741,9 @@
   pointer-events: none;
 }
 .ua-toast {
+  display: flex;
+  align-items: center;
+  gap: var(--ua-space-3);
   padding: var(--ua-space-2) var(--ua-space-3);
   border-radius: var(--ua-radius-md);
   border: 1px solid;
@@ -753,6 +756,23 @@
   opacity: 1;
   transform: translateX(0);
 }
+/* 仅带关闭按钮的 toast 接收指针，其余保持穿透不挡页面 */
+.ua-toast.is-closable {
+  pointer-events: auto;
+}
+.ua-toast-close {
+  padding: 0 2px;
+  border: none;
+  background: none;
+  color: var(--ua-color-text-muted);
+  font-size: 14px;
+  line-height: 1;
+  cursor: pointer;
+  transition: color 0.15s;
+}
+.ua-toast-close:hover {
+  color: var(--ua-color-text);
+}
 .ua-toast-info {
   border-color: var(--ua-color-accent);
   background: color-mix(in srgb, var(--ua-color-accent) 8%, var(--ua-color-bg));