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 皮肤组件库：button / textField / textarea / slider / checkbox / switch / select / menu / radioGroup / accordion / breadcrumb / card / badge / tag / avatar / alert / toast / tooltip / popover / skeleton / spinner / progress / tabs / pagination / modal / drawer / form / formItem / dataTable，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌。
- API:
  - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用
  - textField(props)：文本输入，value 信号双向绑定，disabled 支持布尔或信号禁用
  - inputNumber(props)：数字输入，−/+ 按钮 + 键盘 ↑↓ 调节，value 信号双向绑定，min/max/step 超界自动夹取
  - textarea(props)：多行输入，value 信号双向绑定，disabled 支持布尔或信号禁用
  - slider(props)：滑块，value 信号双向绑定，min/max/step 可配，原生 range 承载键盘交互，右侧可显示当前值
  - checkbox(props)：复选框，checked 信号双向绑定，disabled 支持布尔或信号禁用
  - switchButton(props)：开关，checked 信号双向绑定，disabled 支持布尔或信号禁用
  - select(props)：自绘下拉选择（非原生 select），value 信号双向绑定，点外部 / Esc 关闭，选项弹层带微动画，disabled 支持布尔或信号禁用
  - menu(props)：下拉菜单，触发器 + 自绘弹层，条目支持禁用 / 危险 / 分隔线，↑↓ 环形导航，点外部 / Esc 关闭
  - 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 / focus 延迟 150ms 出场，移出 / 失焦 / Esc 收起
  - popover(props, trigger)：可交互气泡卡片，包裹触发器，默认点击开合 + 点外部 / Esc 收起，content 可放按钮等交互元素
  - skeleton(props)：骨架屏占位，variant = text | rect | circle，text 支持 rows 多行，扫光微动画
  - pagination(props)：独立分页器，page 信号双向绑定，页码过多折叠省略号，首末页禁用翻页，键盘可达
  - spinner(props)：加载指示器，size 控制直径
  - progress(props)：进度条，value 信号驱动 0-100（满格切 success 色）；不传 value 退化为不确定态无限往复
  - tabs(props)：标签页，active 信号双向绑定，滑动指示条 + 方向键环形导航，支持禁用页签
  - stepper(props)：步骤条，done/current/upcoming 三态，active 信号双向绑定，clickable 时已完成步骤可回跳
  - rate(props)：评分星标，value 信号双向绑定，hover 预览移出还原，键盘方向键调节，max 可配
  - 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
- 用法: `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 <name>：查看单个包的清单详情（api / 约定 / 文档步骤）
  - 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 mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components
- 用法: `node packages/tools/cli/bin/ua.js <index|list|info <name>|docs|style|verify|mcp>；仓库内等价于 npm run index / docs / style / verify`
- 约定: 零依赖：只用 node 标准库，Node >= 18
- 约定: 清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生
- 约定: 门禁只增不改：新增校验必须能被人手复现，报错要指出文件与字段