iter(g271): 新增手写签名板组件

packages/skin/ui/src/index.ts

@@ -80,3 +80,4 @@ export { layout } from './layout.js';
 export { jsonViewer } from './jsonViewer.js';
 export { diffView } from './diffView.js';
 export { codeBlock } from './codeBlock.js';
+export { signaturePad } from './signaturePad.js';

packages/skin/ui/src/signaturePad.ts

@@ -0,0 +1,111 @@
+import { effect, h, signal } from '@ui-arch/frame';
+import { trackSize } from './watch.js';
+import type { SignaturePadHandle, SignaturePadProps } from './types.js';
+
+// 缺省画布高度与笔宽：160px 够签一个名字，2px 在 1x 屏上也不显细
+const PAD_H = 160;
+const PEN_W = 2;
+
+/*** 签名板：指针手写，canvas 位图按 DPR 放大保证线条不糊，笔色读 canvas 的 color 走令牌；签字结果写回 value 信号 ***/
+export function signaturePad(props: SignaturePadProps): SignaturePadHandle {
+  // —— 状态集中声明 ——
+  const height = props.height ?? PAD_H; // 画布 CSS 高度
+  const penW = props.penWidth ?? PEN_W; // 笔宽（CSS 像素）
+  const signed = signal(false); // 是否已落笔：决定清空按钮可用性与「未签」提示
+  const canvas = h('canvas', { class: 'ua-sign-canvas', role: 'img', 'aria-label': props.ariaLabel ?? '手写签名区' }) as HTMLCanvasElement;
+  const ctx = canvas.getContext('2d');
+  let drawing = false;                // 指针是否按住
+  let lastX = 0;                      // 上一落点 x（CSS 像素坐标系）
+  let lastY = 0;                      // 上一落点 y
+  let snap = '';                      // 尺寸变化前的内容快照：重设位图会清空画布，先存后用
+
+  /*** 取得当前笔色：读 canvas 计算样式的 color，颜色令牌换了笔色自动跟随 ***/
+  const penColor = (): string => getComputedStyle(canvas).color || '#000';
+
+  /*** 位图尺寸同步：按 CSS 宽 × DPR 设置位图，再把坐标系缩回 CSS 像素，避免高分屏线条发虚 ***/
+  const resize = (): void => {
+    const cssW = canvas.clientWidth || canvas.parentElement?.clientWidth || 320; // 宽度跟随容器，取不到就退 320
+    const ratio = window.devicePixelRatio || 1;
+    const nextW = Math.round(cssW * ratio);
+    const nextH = Math.round(height * ratio);
+    if (canvas.width === nextW && canvas.height === nextH) return; // 尺寸没变：不动位图（也不清内容）
+    snap = signed() ? canvas.toDataURL() : ''; // 有内容才快照，空白不浪费一次编码
+    canvas.width = nextW;
+    canvas.height = nextH;
+    if (!ctx) return;
+    ctx.setTransform(ratio, 0, 0, ratio, 0, 0); // 之后的坐标都按 CSS 像素算
+    ctx.lineCap = 'round'; // 圆头：手写笔迹不该是方角
+    ctx.lineJoin = 'round';
+    if (!snap) return;
+    const img = new Image();
+    img.onload = () => ctx.drawImage(img, 0, 0, cssW, height); // 快照按 CSS 尺寸贴回，缩放后笔迹仍在
+    img.src = snap;
+  };
+
+  /*** 落笔点换算：指针坐标减画布位置，得到 CSS 像素坐标 ***/
+  const pointOf = (e: PointerEvent): [number, number] => {
+    const box = canvas.getBoundingClientRect();
+    return [e.clientX - box.left, e.clientY - box.top];
+  };
+
+  /*** 画到新点：从上一落点连线，单点（点一下）也要画出一个圆点 ***/
+  const stroke = (x: number, y: number): void => {
+    if (!ctx) return;
+    ctx.strokeStyle = penColor();
+    ctx.lineWidth = penW;
+    ctx.beginPath();
+    ctx.moveTo(lastX, lastY);
+    ctx.lineTo(x, y);
+    ctx.stroke();
+    lastX = x;
+    lastY = y;
+  };
+
+  /*** 收笔：写回 dataURL，空画布不算签字 ***/
+  const commit = (): void => {
+    const url = canvas.toDataURL('image/png');
+    if (props.value) props.value(url);
+    if (props.onChange) props.onChange(url);
+  };
+
+  /*** 清空：复位位图 + 状态 + 信号，一次到位（三处不同源会立刻不同步） ***/
+  const clear = (): void => {
+    if (ctx) ctx.clearRect(0, 0, canvas.width, canvas.height);
+    signed(false);
+    snap = '';
+    if (props.value) props.value('');
+    if (props.onChange) props.onChange('');
+  };
+
+  canvas.addEventListener('pointerdown', (e: PointerEvent) => {
+    if (props.disabled === true) return; // 卫语句：布尔禁用直接挡住
+    drawing = true;
+    canvas.setPointerCapture(e.pointerId); // 指针捕获：手滑出画布也继续跟笔
+    [lastX, lastY] = pointOf(e);
+    stroke(lastX, lastY); // 先落一个点，单击也能留下痕迹
+    signed(true);
+  });
+  canvas.addEventListener('pointermove', (e: PointerEvent) => {
+    if (!drawing) return; // 卫语句：没按住不画
+    const [x, y] = pointOf(e);
+    stroke(x, y);
+  });
+  const finish = (): void => {
+    if (!drawing) return; // 卫语句：未落笔不重复提交
+    drawing = false;
+    commit();
+  };
+  canvas.addEventListener('pointerup', finish);
+  canvas.addEventListener('pointercancel', finish);
+  canvas.style.height = `${height}px`; // 高度只在这一次写：resize 里读它，不重复推导
+
+  const clearBtn = h('button', { type: 'button', class: 'ua-sign-clear', onClick: clear }, '清空') as HTMLButtonElement;
+  effect(() => { clearBtn.disabled = !signed() || props.disabled === true || (typeof props.disabled === 'function' && Boolean(props.disabled())); }); // 空白或信号禁用时不给出无效操作
+  const el = h('div', { class: 'ua-sign' }, canvas, h('div', { class: 'ua-sign-bar' }, h('span', { class: 'ua-sign-hint' }, props.hint ?? '在上方区域手写签名'), clearBtn));
+  if (typeof props.disabled === 'function') effect(() => { el.classList.toggle('is-disabled', Boolean(props.disabled && typeof props.disabled === 'function' && props.disabled())); }); // 信号禁用：跟着变灰
+  if (props.disabled === true) el.classList.add('is-disabled');
+  trackSize(el, resize); // 容器宽度变化后重算位图，笔迹按快照贴回
+  requestAnimationFrame(resize); // 首帧：布局完成后再定位图尺寸，避免 clientWidth 为 0
+
+  return { el, clear, toDataURL: () => canvas.toDataURL('image/png'), isEmpty: () => !signed() };
+}

packages/skin/ui/src/types.ts

@@ -1050,3 +1050,22 @@ export interface CodeBlockProps {
   onCopy?: (text: string) => void; // 复制成功回调（参数为实际写入剪贴板的内容）
   ariaLabel?: string;              // 可访问名；缺省「代码块」
 }
+
+/*** 签名板入参 ***/
+export interface SignaturePadProps {
+  value?: Signal<string>;                // 签字结果 dataURL 信号，双向绑定；清空写空串
+  height?: number;                       // 画布高度（px）；缺省 160
+  penWidth?: number;                     // 笔宽（px）；缺省 2
+  hint?: string;                         // 底部提示文案；缺省「在上方区域手写签名」
+  disabled?: boolean | Signal<boolean>;  // 禁用态：布尔或信号，禁用时不响应手写
+  ariaLabel?: string;                    // 画布可访问名；缺省「手写签名区」
+  onChange?: (dataUrl: string) => void;  // 收笔 / 清空时回调（清空回调空串）
+}
+
+/*** 签名板句柄 ***/
+export interface SignaturePadHandle {
+  el: HTMLElement;                       // 组件根（画布 + 底部条）
+  clear(): void;                         // 清空画布并复位信号
+  toDataURL(): string;                   // 取当前签字 PNG dataURL（未签也返回空白图）
+  isEmpty(): boolean;                    // 是否尚未落笔
+}

packages/skin/ui/ua.manifest.json

@@ -94,7 +94,8 @@
       "layout(props, ...children)：布局骨架，页头 / 侧栏 / 内容 / 页脚四区一次成型，侧栏可折叠（collapsed 信号双向绑定）",
       "jsonViewer(props)：JSON 树查看，按层折叠、分支带计数摘要、叶子按类型着色，只读不编辑",
       "diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计",
-      "codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮"
+      "codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮",
+      "signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -4167,6 +4168,56 @@
           "单行代码自动省掉行号列；想彻底不要行号传 lineNumbers: false",
           "不需要复制按钮（例如代码本身是操作步骤）传 copyable: false；连标题都没有时头部整条省掉"
         ]
+      },
+      {
+        "id": "signaturePad",
+        "title": "手写签名 SignaturePad",
+        "demo": "sec-sign",
+        "props": [
+          {
+            "n": "value",
+            "t": "Signal<string>",
+            "d": "签字结果 dataURL 信号，双向绑定；清空写空串"
+          },
+          {
+            "n": "height",
+            "t": "number",
+            "d": "画布高度（px）；缺省 160"
+          },
+          {
+            "n": "penWidth",
+            "t": "number",
+            "d": "笔宽（px）；缺省 2"
+          },
+          {
+            "n": "hint",
+            "t": "string",
+            "d": "底部提示文案；缺省「在上方区域手写签名」"
+          },
+          {
+            "n": "disabled",
+            "t": "boolean | Signal<boolean>",
+            "d": "禁用态：布尔或信号，禁用时不响应手写"
+          },
+          {
+            "n": "ariaLabel",
+            "t": "string",
+            "d": "画布可访问名；缺省「手写签名区」"
+          },
+          {
+            "n": "onChange",
+            "t": "(dataUrl: string) => void",
+            "d": "收笔 / 清空时回调（清空回调空串）"
+          }
+        ],
+        "example": "const pad = signaturePad({ value: sign, height: 140 }); mount('#box', () => pad.el); pad.toDataURL(); pad.clear();",
+        "steps": [
+          "把画布挂上去即可手写：宽度跟随容器、高度由 height 给（缺省 160），不用自己算 DP R",
+          "签字结果在收笔瞬间写回 value 信号（PNG dataURL）；要提交表单就把它塞进字段值，清空会写回空串",
+          "底部「清空」按钮在未落笔或禁用时自动不可点，避免空操作；也能用返回的 handle.clear() 外部触发",
+          "需要判空用 handle.isEmpty()，取图用 handle.toDataURL()；两者与信号同源，不会出现「有图但信号是空」",
+          "禁用传布尔或信号：布尔直接置位，信号随状态变灰并挡住手写；移动端画布已关掉浏览器手势，不会边签边滚页"
+        ]
       }
     ]
   }

packages/skin/ui/ui.css

@@ -5685,3 +5685,58 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
 .ua-code-line:hover {
   background: var(--ua-color-tint-accent-weak);
 }
+
+/* ---- 签名板：画布边框只一道，手写区留白不压内距（笔迹要贴边才好签） ---- */
+.ua-sign {
+  overflow: hidden;
+  border: 1px solid var(--ua-border-subtle);
+  border-radius: var(--ua-radius-md);
+  background: var(--ua-color-surface);
+  color: var(--ua-color-text);
+}
+
+.ua-sign.is-disabled {
+  opacity: 0.6; /* 禁用态整块降权：单个控件灰掉就够，不给画布加遮罩 */
+}
+
+.ua-sign-canvas {
+  display: block;
+  width: 100%;
+  border-bottom: 1px solid var(--ua-border-subtle);
+  cursor: crosshair;
+  touch-action: none; /* 关掉浏览器手势：手写要独占指针，否则移动端会滚页面 */
+}
+
+.ua-sign-bar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--ua-space-2);
+  padding: var(--ua-space-2) var(--ua-space-3);
+}
+
+.ua-sign-hint {
+  color: var(--ua-color-text-faint);
+  font-size: var(--ua-font-size-xs);
+}
+
+.ua-sign-clear {
+  padding: var(--ua-space-1) var(--ua-space-2);
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-sm);
+  background: transparent;
+  color: var(--ua-color-text-secondary);
+  font-size: var(--ua-font-size-xs);
+  cursor: pointer;
+  transition: color var(--ua-duration-fast) var(--ua-ease), border-color var(--ua-duration-fast) var(--ua-ease);
+}
+
+.ua-sign-clear:hover:not(:disabled) {
+  border-color: var(--ua-color-accent);
+  color: var(--ua-color-accent);
+}
+
+.ua-sign-clear:disabled {
+  color: var(--ua-color-text-faint);
+  cursor: not-allowed;
+}