iter(g236): 新增 countdown 倒计时组件，秒级递减自动停表并带句柄控制（73 组件）

packages/skin/ui/src/countdown.ts

@@ -0,0 +1,27 @@
+import { h, signal } from '@ui-arch/frame';
+import type { CountdownHandle, CountdownProps } from './types.js';
+
+/*** 倒计时：秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，句柄可 start / stop / reset ***/
+export function countdown(props: CountdownProps): CountdownHandle {
+  const remain = signal(props.seconds); // 剩余秒数（单一来源，h() 函数型子节点响应式刷新文本）
+  let timer = 0; // setInterval 句柄（0 表示停表中）
+  const fmt = props.format ?? ((s: number): string => `${String(Math.floor(s / 60)).padStart(2, '0')}:${String(s % 60).padStart(2, '0')}`); // 缺省 mm:ss 两位补零
+
+  const stop = (): void => { if (timer) { clearInterval(timer); timer = 0; } }; // 停表并清句柄，幂等
+
+  /*** 开始 / 续跑：重入先停旧表；已归零时视为重开一轮 ***/
+  const start = (): void => {
+    stop();
+    if (remain() <= 0) remain(props.seconds);
+    timer = window.setInterval(() => {
+      const next = Math.max(0, remain() - 1);
+      remain(next);
+      if (next <= 0) { stop(); if (props.onFinish) props.onFinish(); } // 归零即停表并回调，不留负数帧
+    }, 1000);
+  };
+
+  const reset = (): void => { stop(); remain(props.seconds); }; // 复位到总时长并停表
+  const el = h('span', { class: 'ua-countdown', role: 'timer' }, () => fmt(remain())) as HTMLSpanElement;
+  if (props.running ?? true) start(); // 缺省挂载即开始
+  return { el, start, stop, reset };
+}

packages/skin/ui/src/index.ts

@@ -72,3 +72,4 @@ export { commandPalette } from './commandPalette.js';
 export { timePicker } from './timePicker.js';
 export { pinInput } from './pinInput.js';
 export { copyButton } from './copyButton.js';
+export { countdown } from './countdown.js';

packages/skin/ui/src/types.ts

@@ -265,6 +265,22 @@ export interface CopyButtonProps {
   onCopied?: (text: string) => void;    // 复制成功回调（参数为实际写入的内容）
 }
 
+/*** 倒计时入参 ***/
+export interface CountdownProps {
+  seconds: number;                      // 总时长（秒），> 0
+  running?: boolean;                    // 创建即开始倒数；缺省 true
+  format?: (seconds: number) => string; // 展示格式化；缺省 mm:ss 两位补零
+  onFinish?: () => void;                // 归零回调（自动停表后触发）
+}
+
+/*** 倒计时句柄 ***/
+export interface CountdownHandle {
+  el: HTMLSpanElement;  // 根节点（role=timer，文本随剩余秒数响应式刷新）
+  start: () => void;    // 开始 / 续跑（已归零则重开一轮）
+  stop: () => void;     // 暂停（保留剩余秒数）
+  reset: () => void;    // 复位到总时长并停表
+}
+
 /*** 空状态入参 ***/
 export interface EmptyProps {
   title?: string;       // 主标题；缺省不渲染

packages/skin/ui/ua.manifest.json

@@ -86,7 +86,8 @@
       "commandPalette(props)：命令面板，⌘K / Ctrl+K 唤起，输入即过滤（主文案/说明/关键词三层），↑↓ 环形选择 + 回车执行 + Esc 收起，选中与关闭都归还焦点；返回 { el, open, close } 句柄",
       "timePicker(props)：时间选择，时 / 分两列弹层，value 信号双向绑定 HH:mm，分钟可配步长，Esc 收起",
       "pinInput(props)：验证码输入，N 格单字符数字输入，输入自动进格、退格回删、方向键移格、粘贴自动分发，value 信号双向绑定，mask 可密文显示",
-      "copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand"
+      "copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand",
+      "countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -3808,6 +3809,43 @@
           "label / copiedLabel 可改文案；variant / size 透传给内部 button，视觉与普通按钮完全一致",
           "非安全上下文（http）或旧浏览器自动降级为隐藏 textarea + execCommand，无需业务处理兼容"
         ]
+      },
+      {
+        "id": "countdown",
+        "title": "倒计时 Countdown",
+        "demo": "sec-countdown",
+        "props": [
+          {
+            "n": "seconds",
+            "t": "number",
+            "r": 1,
+            "d": "总时长（秒），> 0"
+          },
+          {
+            "n": "running",
+            "t": "boolean",
+            "df": "true",
+            "d": "创建即开始倒数；传 false 用句柄 start 手动启动"
+          },
+          {
+            "n": "format",
+            "t": "(seconds: number) => string",
+            "d": "展示格式化；缺省 mm:ss 两位补零"
+          },
+          {
+            "n": "onFinish",
+            "t": "() => void",
+            "k": 1,
+            "d": "归零回调（自动停表后触发）"
+          }
+        ],
+        "example": "const cd = countdown({ seconds: 60, onFinish: () => console.log('结束') }); // cd.start / stop / reset",
+        "steps": [
+          "传 seconds 即可用，缺省挂载即开始、mm:ss 展示；返回句柄 { el, start, stop, reset }",
+          "running: false 先摆好再手动 start，典型场景是「发送验证码」后才开始 60s 重发倒计时",
+          "归零自动停表并触发 onFinish；之后 start() 会重开一轮，reset() 复位到总时长",
+          "format 自定义展示：如只显示秒 (s) => `${s}s`，或带上小时位"
+        ]
       }
     ]
   }

packages/skin/ui/ui.css

@@ -5197,3 +5197,8 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
   font-variant-numeric: tabular-nums; /* 数字等宽：换位不左右窜 */
   caret-color: var(--ua-color-accent);
 }
+
+/* ---- 倒计时（countdown） ---- */
+.ua-countdown {
+  font-variant-numeric: tabular-nums; /* 数字等宽：秒跳不抖动 */
+}