UI/llms.txt

# @ui-arch 私人组件库索引

> 本文件由 `ua index` 自动生成，请勿手改。机器可读版：`.ua/index.json`。
> Agent 可通过 `ua mcp`（stdio MCP server）直接查询注册表。

## @ui-arch/frame (v0.1.0)

- 类型: headless-core · 目录: packages/core/frame
- 描述: 自研微框架：signal / computed / effect 信号系统 + hyperscript（h）DOM 层。函数值属性与函数型子节点自动响应式；renderList 做列表整体替换；零依赖、无虚拟 DOM。
- API:
  - signal(initial) -> Signal<T>：无参读值并收集依赖，传参写值并触发订阅
  - effect(fn)：立即执行并追踪依赖，信号变化自动重跑
  - computed(fn)：由信号派生的只读计算值
  - h(tag, props, ...children)：hyperscript；on* 绑事件，函数值属性/子节点自动响应式
  - renderList(el, fn)：信号变化时整体替换容器子节点
  - mount(target, view)：挂载视图
- 用法: `const count = signal(0); mount('#app', () => h('button', { onClick: () => count(count() + 1) }, () => `count = ${count()}`))`
- 约定: 组件 = 返回 DOM 节点的普通函数，不做类组件与生命周期抽象
- 约定: 跨系统状态（如 table-core）用桥接信号：subscribe 里递增 version 信号

## @ui-arch/table-core (v0.1.0)

- 类型: headless-core · 目录: packages/core/table-core
- 描述: Headless table state machine: immutable state, dispatch/reducer, composable derive pipeline (filter -> sort -> paginate) with per-stage memoization. No DOM, no framework dependency.
- API:
  - createTable(options) -> TableInstance: create headless table instance
  - sortPlugin(options?) -> multi-column sorting plugin (asc -> desc -> off cycle)
  - filterPlugin(options?) -> column filter plugin (default substring match, custom predicate supported)
  - paginationPlugin() -> client-side pagination with page clamping, exposes setPage/nextPage/prevPage/getPageInfo
  - selectionPlugin() -> rowKey-based selection, exposes selectAllVisible
- 用法: `const table = createTable({ data, columns, rowKey: 'id', plugins: [filterPlugin(), sortPlugin(), paginationPlugin()], initialState: { pagination: { page: 1, pageSize: 20 } } }); table.dispatch({ type: 'toggleSort', key: 'name' }); table.getVisibleRows()`
- 约定: selection/expanded must store rowKey, never row index
- 约定: derive pipeline order is fixed: filter -> sort -> paginate
- 约定: actions are the only way to mutate state; state is immutable

## @ui-arch/tokens (v0.1.0)

- 类型: design-tokens · 目录: packages/design/tokens
- 描述: Single source of design tokens. Skin packages consume CSS variables only - hardcoded colors inside skins are forbidden. Dark theme overrides values under [data-theme='dark'], never names.
- API:
  - tokens.css: import '@ui-arch/tokens/tokens.css' once at app root
  - tokens.json: programmatic access for tools and agents
- 用法: `import '@ui-arch/tokens/tokens.css'; then use var(--ua-color-accent) etc. in any skin package`

## @ui-arch/ui (v0.1.0)

- 类型: skin-dom · 目录: packages/skin/ui
- 描述: DOM 皮肤组件库：表单 / 反馈 / 浮层 / 导航 / 数据展示，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌（组件全量见 api.exports 或刚体清单）
- API:
  - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交）
  - textField(props)：文本输入，value 信号双向绑定，disabled 支持布尔或信号，onInput 输入回调；prefix/suffix 可选渲染为输入框内侧附加块，clearable 开启后有值即显一键清空按钮
  - inputNumber(props)：数字输入，−/+ 按钮与键盘 ↑↓ 调节（长按连发步进），min/max/step 夹取；prefix/suffix 可选渲染为整组前后附加块
  - textarea(props)：多行输入，value 信号双向绑定，disabled 支持布尔或信号，rows 控行数；prefix/suffix 可选渲染为上下附加块，maxCount 显示实时字数并设原生上限
  - slider(props)：滑块，value 信号双向绑定，min/max/step 可配，原生 range 承载键盘交互，右侧可显示当前值
  - checkbox(props)：复选框，checked 信号双向绑定，disabled 支持布尔或信号禁用
  - switchButton(props)：开关，checked 信号双向绑定，disabled 支持布尔或信号禁用
  - select(props)：自绘下拉选择（非原生 select），value 信号双向绑定，点外部 / Esc 关闭，选项弹层带微动画，disabled 支持布尔或信号禁用，空间不足自动翻转，键入字母快跳选项；searchable 开启弹层搜索框，clearable 有值时给清空按钮
  - menu(props)：下拉菜单，触发器 + 自绘弹层，条目支持禁用 / 危险 / 分隔线，↑↓ 环形导航，点外部 / Esc 关闭，空间不足自动翻转，键入字母快跳菜单项
  - flip(trigger, panel, preferred)：浮层上下翻转判定，按触发器与面板的视口几何决定 preferred 方位放不下时是否翻转，返回实际生效方位 'top' | 'bottom'
  - radioGroup(props)：单选组，options + value 信号双向绑定，disabled 整组禁用
  - accordion(props)：折叠面板，标题按钮 + grid 行高过渡，单开（手风琴）或多开，支持禁用面板与 active 信号受控
  - breadcrumb(props)：面包屑，nav + ol 语义结构，末项为当前页（aria-current），有 href 走原生链接、无 href 交给 onNavigate
  - card(props, ...children)：卡片容器
  - badge(props)：徽标，variant = default | success | warning | danger
  - tag(props)：可关闭标签，variant 五档语义色，closable + onClose 支持从数据源移除（纯展示请用 badge）
  - avatar(props)：头像，有 src 渲染图片（alt 用名称）、无 src 用首字占位，size 可调 + 四档语义底色
  - alert(props)：提示条，variant 四档语义色 + 可选 title 与 closable 关闭按钮，role=alert 读屏可播报
  - toast.info/success/warning/error(message, duration?)：消息提示工厂，右上角堆叠，默认 3s 自动消失（悬停暂停、移出续时），出入场微动画；showToast(props) 为完整入参版本（closable 显示关闭按钮，同屏最多 4 条）
  - tooltip(props, trigger)：包裹式悬浮提示，hover / 键盘聚焦延迟出场，Esc 收起；触摸屏按下即出、抬手延迟 1.2s 收起，气泡 pointer-events: none 不挡点击
  - popover(props, trigger)：可交互气泡卡片，包裹触发器，默认点击开合 + 点外部 / Esc 收起，content 可放按钮等交互元素；视口一侧空间不足时自动翻转
  - skeleton(props)：骨架屏占位，variant = text | rect | circle，text 支持 rows 多行，扫光微动画
  - pagination(props)：独立分页器，page 信号双向绑定，页码过多折叠省略号，首末页禁用翻页，jumpable 时末尾可输入页码直接跳转，键盘可达；pageSizes 可切每页条数
  - spinner(props)：加载指示器，size 控制直径
  - progress(props)：进度条，value 信号驱动 0-100（满格切 success 色）；不传 value 退化为不确定态无限往复
  - tabs(props)：标签页，active 信号双向绑定，滑动指示条 + 方向键环形导航，支持禁用页签；页签项 closable 时带关闭按钮（聚焦后 Delete 同样可关），关闭只回调 onClose 由调用方摘数据
  - stepper(props)：步骤条，done/current/upcoming 三态，active 信号双向绑定，clickable 时已完成步骤可回跳
  - rate(props)：评分星标，value 信号双向绑定，hover 预览移出还原，键盘方向键调节，max 可配
  - empty(props)：空状态占位，title/description 可选，action 放操作区
  - divider(props)：分隔线，水平/垂直两种方向，可带居中文案标签，dashed 切虚线
  - space(props)：间距容器，flex gap 统一子元素间距，direction / size / align / justify / wrap / block 可调
  - modal(props, ...children)：弹窗，open 信号驱动显隐，Esc / 遮罩 / × 关闭，size 三档宽度，footer 提供底部操作区
  - drawer(props, ...children)：抽屉，open 信号驱动侧滑面板，placement 左右可配、width 可调、footer 操作区，遮罩 / × / Esc 关闭
  - form(props, items)：表单容器，布局 + 聚合校验，全部通过才触发 onSubmit
  - formItem(props, control)：表单字段，label + 必填红星 + 规则校验 + 错误区，返回 { el, validate } 句柄
  - dataTable(props)：数据表格，粘性表头 / 行选择（全选三态）/ 排序 / 筛选 / 分页 / 空状态；loading 为真时数据行换骨架行且筛选/翻页禁用，内核为 table-core
  - image(props)：图片，缩略图点击 / 回车开遮罩大图预览（Esc 或点击遮罩关闭），width 控制缩略宽，加载失败自动落占位（fallback 自定义文案）
  - timeline(props)：时间线，items 按序渲染纵向事件流（标题 / 时间 / 正文 + 语义色节点），mode 控制轴线左右，pending 追加进行中节点
  - segmented(props)：分段控制器，胶囊分段 + 滑动滑块，value 信号双向绑定，←→ 环形导航，整组或单项可禁用
  - descriptions(props)：描述列表，items(label/value/span) 铺进 column 列网格，bordered 切表格形态，窄屏自动单列
  - statistic(props)：统计数值，标题 + 大号数字 + 前后缀 + 环比趋势，value 变化时 rAF 滚动过渡（400ms easeOutCubic），减弱动效偏好下直落终值
  - list(props)：列表，header/footer 外壳 + 条目 avatar/title/description/extra，onItemClick 让条目可点击，items 为空回落空状态
  - carousel(props)：轮播，items 横排位移，指示点/箭头/←→ 键切换，autoplay 毫秒自动前进且悬停暂停，index 信号可外部受控
  - tree(props)：树形，递归节点 + 箭头展开/收起 + 点选节点，键盘 Enter 选中、→ 展开、← 收起，禁用节点不响应
  - upload(props)：文件选择，点击或拖拽入列，清单可逐个移除，onChange 回传文件数组（不内置上传请求）
  - notification(props)：右下角通知卡片（标题 + 描述 + 操作区），返回 { el, close } 句柄，缺省常驻需手动关闭
  - result(props)：结果页，status 四档语义色 + 标题 + 说明 + 操作区，用于提交完成/校验失败等终态
  - transfer(props)：穿梭框，左右两栏勾选后整体搬运，targetKeys 信号双向绑定，两栏各自搜索与全选（含半选），禁用条目不参与搬运也不可勾选
  - cascader(props)：级联选择，多列联动面板（悬停下钻 / 点击提交），value 为路径数组信号，changeOnSelect 允许停在中间层，全键盘可操作
  - splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号
  - autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想
  - datePicker(props)：日期选择，单月网格 + 翻月 / 今天快捷键，value 为 YYYY-MM-DD 信号，min/max 闭区间限制，方向键逐日逐周可导航
  - backTop(props)：返回顶部悬浮按钮，越过阈值才浮现，外环 conic-gradient 显示已滚比例，点击平滑回顶
  - colorPicker(props)：颜色选择，预设色板（缺省语义令牌色）+ 原生取色器 + 手输 CSS 颜色串，value 为颜色串信号
  - tour(props)：引导漫游，返回 { el, start, close } 句柄；聚光框按 target 选择器定位，卡片自动选方位，Esc / 跳过走 onClose
  - watermark(props, ...children)：内容容器 + 平铺水印覆盖层，canvas 生成单元、颜色取自令牌，覆盖层不挡交互
  - checkboxGroup(props)：多选组，value 为数组信号，min/max 用禁用边界项实现（不抛错），checkAll 支持半选且只统计未禁用项
  - affix(props, ...children)：固钉，滚过 offset 后内容转 fixed 贴顶、外层保留占位高度，固定后宽度随容器自适应
  - multiSelect(props)：多选下拉，标签式回显 + 可搜索弹层，点选不收起便于连续多选，max 到限后未选项禁用
  - anchor(props)：锚点导航，竖排区块链接，滚动时按目标位置高亮当前区块（aria-current 同步），点击按 offset 偏移量平滑定位并回写 hash；container 可指定内滚容器
  - popconfirm(props, trigger)：二次确认气泡，挂在任意触发器上，就地确认危险操作；确定后先收起再回调，取消 / 点外部 / Esc 走 onCancel，展开即聚焦「取消」
- 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')`
- 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号
- 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调
- 约定: 语义色 variant 四档：default|info / success / warning / danger，一律来自令牌，禁止硬编码颜色
- 约定: 无障碍基线：装饰性占位（skeleton）aria-hidden、加载指示（spinner）role=status、关闭按钮必须 aria-label、弹层弹窗 aria-haspopup/expanded、读屏可见的状态一律同步 aria-*

## @ui-arch/cli (v0.1.0)

- 类型: tooling · 目录: packages/tools/cli
- 描述: ua 命令行与 MCP 注册表服务：把各包 ua.manifest.json 汇总成机器可读索引（.ua/index.json）、Agent 全量文档（llms-full.txt）与人类文档站，并提供清单一致性门禁。
- API:
  - ua index：扫描 packages/ 两层目录的 ua.manifest.json，生成 .ua/index.json 与 llms.txt
  - ua list：列出注册表内所有包与组件数
  - ua info <包名|组件id>：包名返回摘要，组件 id 返回 props 表 + 步骤 + 示例；--json 输出原始清单
  - ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt
  - ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1
  - ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在）
  - ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1
  - ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components
- 用法: `node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id>|docs|tokens|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify`
- 约定: 零依赖：只用 node 标准库，Node >= 18
- 约定: 清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生
- 约定: 门禁只增不改：新增校验必须能被人手复现，报错要指出文件与字段