iter(g270): 新增代码块组件

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-26T14:53:11.893Z",
+  "generatedAt": "2026-10-26T14:54:40.928Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -222,7 +222,8 @@
           "inputTag(props)：标签输入，输入后回车 / 逗号成标签、chip 可单个删除、空框退格删末个，value 信号双向绑定，max 满额自动禁输",
           "layout(props, ...children)：布局骨架，页头 / 侧栏 / 内容 / 页脚四区一次成型，侧栏可折叠（collapsed 信号双向绑定）",
           "jsonViewer(props)：JSON 树查看，按层折叠、分支带计数摘要、叶子按类型着色，只读不编辑",
-          "diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计"
+          "diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计",
+          "codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮"
         ],
         "keyTypes": [
           "ButtonProps",
@@ -4240,6 +4241,61 @@
               "顶部统计条给 +N / −N，读屏在容器上直接播报同一组数字，不必逐行听",
               "超大文本（中间段行数乘积超过 40 万）会退化成「整段替换」——语义仍对，只是不再逐行对齐；要逐行对齐就先分段比对"
             ]
+          },
+          {
+            "id": "codeBlock",
+            "title": "代码块 CodeBlock",
+            "demo": "sec-code",
+            "props": [
+              {
+                "n": "code",
+                "t": "string",
+                "d": "代码原文：显示与复制都用它（不读 DOM，避免行号混进剪贴板）"
+              },
+              {
+                "n": "lang",
+                "t": "string",
+                "d": "语言名（如 ts / css）；无 title 时作头部标题"
+              },
+              {
+                "n": "title",
+                "t": "string",
+                "d": "头部标题（如文件名）；优先于 lang"
+              },
+              {
+                "n": "lineNumbers",
+                "t": "boolean",
+                "d": "是否显示行号列；缺省 true（单行代码自动省略）"
+              },
+              {
+                "n": "maxHeight",
+                "t": "number",
+                "d": "代码区最高高度（px），超出在框内滚动；缺省不限高"
+              },
+              {
+                "n": "copyable",
+                "t": "boolean",
+                "d": "右上角是否出现复制按钮；缺省 true"
+              },
+              {
+                "n": "onCopy",
+                "t": "(text: string) => void",
+                "d": "复制成功回调（参数为实际写入剪贴板的内容）"
+              },
+              {
+                "n": "ariaLabel",
+                "t": "string",
+                "d": "可访问名；缺省「代码块」"
+              }
+            ],
+            "example": "codeBlock({ code: source, title: 'main.ts', lang: 'ts', maxHeight: 320 })",
+            "steps": [
+              "把代码原文交给 code：显示与复制都读这一份，不要从 DOM 里取文本（行号会污染剪贴板）",
+              "头部标题用 title（文件名）或 lang（语言名），两者都给时 title 优先",
+              "长代码给 maxHeight，超出在框内滚动；滚动条已是统一细条，暗色下不会露原生亮条",
+              "单行代码自动省掉行号列；想彻底不要行号传 lineNumbers: false",
+              "不需要复制按钮（例如代码本身是操作步骤）传 copyable: false；连标题都没有时头部整条省掉"
+            ]
           }
         ]
       },

AGENTS.md

@@ -21,7 +21,7 @@
 
 - `packages/core/table-core`（@ui-arch/table-core）：Headless 表格逻辑内核
 - `packages/core/frame`（@ui-arch/frame）：signal + hyperscript 微框架
-- `packages/skin/ui`（@ui-arch/ui）：79 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
+- `packages/skin/ui`（@ui-arch/ui）：80 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
 - `packages/design/tokens`（@ui-arch/tokens）：设计令牌
 - `packages/tools/cli`（@ui-arch/cli）：`ua` 命令行 + MCP 注册表服务（private）
 - `apps/demo`（@ui-arch/demo）：交互演示，产物 apps/demo/dist/demo.html

ARCHITECTURE.md

@@ -34,7 +34,7 @@ ui-arch-mvp/
 │   │   ├── table-core/       # 表格状态内核
 │   │   └── frame/            # 信号 + hyperscript 微框架
 │   ├── skin/                 # 皮肤层（DOM 组件，可发布）
-│   │   └── ui/               # 79 个组件 + ui.css
+│   │   └── ui/               # 80 个组件 + ui.css
 │   ├── design/               # 资产层（可发布）
 │   │   └── tokens/           # --ua-* 设计令牌
 │   └── tools/                # 工程层（private，不发布）

README.md

@@ -12,13 +12,13 @@ npm run docs            # 生成人类文档站 apps/docs/index.html + Agent 全
 npm run changelog       # 依据 git 提交史重写 CHANGELOG.md（发版前跑；changelog:check 可查漂移）
 ```
 
-## 组件（共 79 个）
+## 组件（共 80 个）
 
 <!-- ua:components -->
-accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · commandPalette · copyButton · countdown · dataTable · datePicker · descriptions · diffView · divider · drawer · empty · floatButton · form · grid · highlight · image · inputNumber · inputTag · jsonViewer · kbd · layout · link · list · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark
+accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · codeBlock · colorPicker · commandPalette · copyButton · countdown · dataTable · datePicker · descriptions · diffView · divider · drawer · empty · floatButton · form · grid · highlight · image · inputNumber · inputTag · jsonViewer · kbd · layout · link · list · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark
 <!-- /ua:components -->
 
-分组：表单（button / copyButton / textField / inputNumber / inputTag / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic / countdown）、浮层（tooltip / popover / popconfirm / modal / drawer / menu / commandPalette）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / jsonViewer / diffView / descriptions / card / list / kbd / highlight / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / layout / link / space / divider / splitter / backTop / affix / tour / watermark）。
+分组：表单（button / copyButton / textField / inputNumber / inputTag / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic / countdown）、浮层（tooltip / popover / popconfirm / modal / drawer / menu / commandPalette）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / jsonViewer / diffView / codeBlock / descriptions / card / list / kbd / highlight / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / layout / link / space / divider / splitter / backTop / affix / tour / watermark）。
 
 ## 可访问性约定
 
@@ -34,7 +34,7 @@ accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup
 |---|---|
 | `packages/core/frame` | @ui-arch/frame：signal / computed / effect + hyperscript（无虚拟 DOM） |
 | `packages/core/table-core` | @ui-arch/table-core：headless 表格（filter → sort → paginate 派生管线） |
-| `packages/skin/ui` | @ui-arch/ui：79 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
+| `packages/skin/ui` | @ui-arch/ui：80 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
 | `packages/design/tokens` | @ui-arch/tokens：设计令牌（暗色只换值不换名） |
 | `packages/tools/cli` | @ui-arch/cli：`ua` 命令行与 stdio MCP server |
 | `apps/demo` | 交互演示（esbuild 打包成单文件） |

apps/demo/main.ts

@@ -24,6 +24,7 @@ import {
   cascader,
   checkbox,
   checkboxGroup,
+  codeBlock,
   colorPicker,
   timePicker,
   commandPalette,
@@ -1765,6 +1766,24 @@ const content = h(
       ].join('\n'),
     }),
   ),
+  section(
+    'sec-code',
+    '代码块',
+    'codeBlock：等宽多行 + 行号列 + 头部标题，右上角一键复制原文；行号是装饰、不进剪贴板，只做展示不高亮。',
+    codeBlock({
+      title: 'sum.ts',
+      lang: 'ts',
+      maxHeight: 200,
+      code: [
+        'export function sum(a: number, b: number): number {',
+        '  if (typeof a !== \'number\') throw new TypeError(\'a 必须是数字\');',
+        '  return a + b;',
+        '}',
+        '',
+        '// 用法：sum(1, 2) === 3',
+      ].join('\n'),
+    }),
+  ),
 );
 
 // 悬浮按钮：fixed 定位，挂 body 不参与页面布局

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T14:53:11.893Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T14:54:40.928Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -2258,6 +2258,35 @@ diffView({ before: oldText, after: newText })
 
 现场演示：apps/docs/demo.html#sec-diff
 
+### codeBlock — 代码块 CodeBlock
+
+参数：
+
+- code：string —— 代码原文：显示与复制都用它（不读 DOM，避免行号混进剪贴板）
+- lang：string —— 语言名（如 ts / css）；无 title 时作头部标题
+- title：string —— 头部标题（如文件名）；优先于 lang
+- lineNumbers：boolean —— 是否显示行号列；缺省 true（单行代码自动省略）
+- maxHeight：number —— 代码区最高高度（px），超出在框内滚动；缺省不限高
+- copyable：boolean —— 右上角是否出现复制按钮；缺省 true
+- onCopy：(text: string) => void —— 复制成功回调（参数为实际写入剪贴板的内容）
+- ariaLabel：string —— 可访问名；缺省「代码块」
+
+示例：
+
+```
+codeBlock({ code: source, title: 'main.ts', lang: 'ts', maxHeight: 320 })
+```
+
+手把手：
+
+1. 把代码原文交给 code：显示与复制都读这一份，不要从 DOM 里取文本（行号会污染剪贴板）
+2. 头部标题用 title（文件名）或 lang（语言名），两者都给时 title 优先
+3. 长代码给 maxHeight，超出在框内滚动；滚动条已是统一细条，暗色下不会露原生亮条
+4. 单行代码自动省掉行号列；想彻底不要行号传 lineNumbers: false
+5. 不需要复制按钮（例如代码本身是操作步骤）传 copyable: false；连标题都没有时头部整条省掉
+
+现场演示：apps/docs/demo.html#sec-code
+
 API 速览：
 
 - button(props)：按钮，variant 三档视觉强度，disabled / loading 支持布尔或信号动态同步（loading 转圈并禁点），onClick 点击回调
@@ -2341,6 +2370,7 @@ API 速览：
 - layout(props, ...children)：布局骨架，页头 / 侧栏 / 内容 / 页脚四区一次成型，侧栏可折叠（collapsed 信号双向绑定）
 - jsonViewer(props)：JSON 树查看，按层折叠、分支带计数摘要、叶子按类型着色，只读不编辑
 - diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计
+- codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮
 
 一行用法：
 

llms.txt

@@ -128,6 +128,7 @@
   - layout(props, ...children)：布局骨架，页头 / 侧栏 / 内容 / 页脚四区一次成型，侧栏可折叠（collapsed 信号双向绑定）
   - jsonViewer(props)：JSON 树查看，按层折叠、分支带计数摘要、叶子按类型着色，只读不编辑
   - diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计
+  - codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮
 - 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')`
 - 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号
 - 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调

packages/skin/ui/src/codeBlock.ts

@@ -0,0 +1,30 @@
+import { h } from '@ui-arch/frame';
+import { copyButton } from './copyButton.js';
+import type { CodeBlockProps } from './types.js';
+
+/*** 代码块：等宽渲染多行代码，可选行号列与标题行（语言 / 文件名），右上角一键复制原文；只做展示不做高亮 ***/
+export function codeBlock(props: CodeBlockProps): HTMLElement {
+  const lines = props.code.replace(/\r?\n$/, '').split(/\r?\n/); // 末尾换行不生成空行：复制走原文，显示不多一行
+  const showNo = props.lineNumbers !== false && lines.length > 1; // 单行代码给行号只是噪音
+  const body = h(
+    'div',
+    { class: 'ua-code-body' },
+    ...lines.map((text, i) => h(
+      'div',
+      { class: 'ua-code-line' },
+      showNo ? h('span', { class: 'ua-code-no', 'aria-hidden': 'true' }, String(i + 1)) : null, // 行号是装饰，读屏跳过
+      h('span', { class: 'ua-code-text' }, text || ' '), // 空行补一个空格，撑住行高
+    )),
+  );
+  if (props.maxHeight !== undefined) body.style.maxHeight = `${props.maxHeight}px`; // 只在给了上限时限高，超出内部滚动
+  const title = props.title ?? props.lang; // 标题优先用文件名，其次语言名
+  const head = props.copyable === false && !title
+    ? null // 既无标题也不可复制：整个头部省掉，不留空条
+    : h(
+      'div',
+      { class: 'ua-code-head' },
+      title ? h('span', { class: 'ua-code-title' }, title) : h('span', null, ''),
+      props.copyable === false ? null : copyButton({ text: props.code, label: '复制', size: 'sm', variant: 'ghost', onCopied: props.onCopy }),
+    );
+  return h('div', { class: 'ua-code', role: 'group', 'aria-label': props.ariaLabel ?? '代码块' }, head, body);
+}

packages/skin/ui/src/index.ts

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

packages/skin/ui/src/types.ts

@@ -1038,3 +1038,15 @@ export interface DiffViewProps {
   showStats?: boolean;             // 是否在顶部显示 +N / −N 统计条；缺省 true
   ariaLabel?: string;              // 可访问名；缺省自动播报「新增 N 行，删除 M 行」
 }
+
+/*** 代码块入参 ***/
+export interface CodeBlockProps {
+  code: string;                    // 代码原文：显示与复制都用它（不读 DOM，避免行号混进剪贴板）
+  lang?: string;                   // 语言名（如 ts / css）；无 title 时作头部标题
+  title?: string;                  // 头部标题（如文件名）；优先于 lang
+  lineNumbers?: boolean;           // 是否显示行号列；缺省 true（单行代码自动省略）
+  maxHeight?: number;              // 代码区最高高度（px），超出在框内滚动；缺省不限高
+  copyable?: boolean;              // 右上角是否出现复制按钮；缺省 true
+  onCopy?: (text: string) => void; // 复制成功回调（参数为实际写入剪贴板的内容）
+  ariaLabel?: string;              // 可访问名；缺省「代码块」
+}

packages/skin/ui/ua.manifest.json

@@ -93,7 +93,8 @@
       "inputTag(props)：标签输入，输入后回车 / 逗号成标签、chip 可单个删除、空框退格删末个，value 信号双向绑定，max 满额自动禁输",
       "layout(props, ...children)：布局骨架，页头 / 侧栏 / 内容 / 页脚四区一次成型，侧栏可折叠（collapsed 信号双向绑定）",
       "jsonViewer(props)：JSON 树查看，按层折叠、分支带计数摘要、叶子按类型着色，只读不编辑",
-      "diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计"
+      "diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计",
+      "codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -4111,6 +4112,61 @@
           "顶部统计条给 +N / −N，读屏在容器上直接播报同一组数字，不必逐行听",
           "超大文本（中间段行数乘积超过 40 万）会退化成「整段替换」——语义仍对，只是不再逐行对齐；要逐行对齐就先分段比对"
         ]
+      },
+      {
+        "id": "codeBlock",
+        "title": "代码块 CodeBlock",
+        "demo": "sec-code",
+        "props": [
+          {
+            "n": "code",
+            "t": "string",
+            "d": "代码原文：显示与复制都用它（不读 DOM，避免行号混进剪贴板）"
+          },
+          {
+            "n": "lang",
+            "t": "string",
+            "d": "语言名（如 ts / css）；无 title 时作头部标题"
+          },
+          {
+            "n": "title",
+            "t": "string",
+            "d": "头部标题（如文件名）；优先于 lang"
+          },
+          {
+            "n": "lineNumbers",
+            "t": "boolean",
+            "d": "是否显示行号列；缺省 true（单行代码自动省略）"
+          },
+          {
+            "n": "maxHeight",
+            "t": "number",
+            "d": "代码区最高高度（px），超出在框内滚动；缺省不限高"
+          },
+          {
+            "n": "copyable",
+            "t": "boolean",
+            "d": "右上角是否出现复制按钮；缺省 true"
+          },
+          {
+            "n": "onCopy",
+            "t": "(text: string) => void",
+            "d": "复制成功回调（参数为实际写入剪贴板的内容）"
+          },
+          {
+            "n": "ariaLabel",
+            "t": "string",
+            "d": "可访问名；缺省「代码块」"
+          }
+        ],
+        "example": "codeBlock({ code: source, title: 'main.ts', lang: 'ts', maxHeight: 320 })",
+        "steps": [
+          "把代码原文交给 code：显示与复制都读这一份，不要从 DOM 里取文本（行号会污染剪贴板）",
+          "头部标题用 title（文件名）或 lang（语言名），两者都给时 title 优先",
+          "长代码给 maxHeight，超出在框内滚动；滚动条已是统一细条，暗色下不会露原生亮条",
+          "单行代码自动省掉行号列；想彻底不要行号传 lineNumbers: false",
+          "不需要复制按钮（例如代码本身是操作步骤）传 copyable: false；连标题都没有时头部整条省掉"
+        ]
       }
     ]
   }

packages/skin/ui/ui.css

@@ -4995,7 +4995,8 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
 .ua-timepicker-col,
 .ua-layout-content,
 .ua-json,
-.ua-diff {
+.ua-diff,
+.ua-code-body {
   scrollbar-width: thin; /* 标准属性：Firefox / Chromium 121+ 生效，细条不挤内容 */
   scrollbar-color: var(--ua-color-scrollbar) transparent; /* 拇指走令牌、轨道透明，避免画出方块底 */
 }
@@ -5629,3 +5630,58 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
 .ua-diff-row.is-del .ua-diff-sign {
   color: var(--ua-color-danger);
 }
+
+/* ---- 代码块：等宽 + 行号靠右，头部只放标题与复制，不叠边框（容器已有一道） ---- */
+.ua-code {
+  overflow: hidden;
+  border: 1px solid var(--ua-border-subtle);
+  border-radius: var(--ua-radius-md);
+  background: var(--ua-color-surface-inset);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; /* 等宽：代码缩进与对齐是语义的一部分 */
+  font-size: var(--ua-font-size-sm);
+  line-height: var(--ua-leading-normal);
+}
+
+.ua-code-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--ua-space-2);
+  padding: var(--ua-space-1) var(--ua-space-2) var(--ua-space-1) var(--ua-space-3);
+  border-bottom: 1px solid var(--ua-border-subtle);
+  background: var(--ua-color-surface);
+}
+
+.ua-code-title {
+  color: var(--ua-color-text-muted);
+  font-size: var(--ua-font-size-xs);
+}
+
+.ua-code-body {
+  overflow: auto;
+  padding: var(--ua-space-2) 0;
+}
+
+.ua-code-line {
+  display: flex;
+  gap: var(--ua-space-3);
+  padding: 0 var(--ua-space-3);
+  white-space: pre; /* 长行横向滚动而不是折行：折行会让行号对不上内容 */
+}
+
+.ua-code-no {
+  flex: 0 0 auto;
+  min-width: var(--ua-space-4);
+  color: var(--ua-color-text-faint);
+  text-align: right;
+  user-select: none; /* 行号不进复制内容：复制按钮走原文，手动选择也不该带走行号 */
+}
+
+.ua-code-text {
+  flex: 1 1 auto;
+}
+
+/* 悬停整行提亮一档：读长代码时能追住当前行 */
+.ua-code-line:hover {
+  background: var(--ua-color-tint-accent-weak);
+}