niuma-ui 1.3.8 → 2.0.0

package/CHANGELOG.md

@@ -6,6 +6,48 @@
 
 ## [Unreleased]
 
+### 变更
+
+- 单测放到对应模块的 `__tests__/`；跨组件冒烟仍留在 `src/__tests__/`。
+- 每个组件目录增加 `index.ts`，`src/index.ts` 只从目录再导出。
+- `src/lib` 并入 `src/utils`。
+- `RsTreeSelect` 独立目录 `components/tree-select/`。组件与组件之间按 slug 平铺；归类只写文档站 `basic` / `form` / `nav` / `feedback` / `data` / `editor`。
+- 每个组件内部为 `index.ts` + `src/` + 可选 `style/` + `__tests__/`。
+- 表格 `src/` 再拆：`table-header` / `table-body` / `table-footer` / `composables` / `context` / `features` / `utils`。
+- 架构契约补齐目录规范：组件四槽、`src/` 再拆门槛、仓库根、`package.json` 发布面（`docs/components.md` §3）。
+
+## [2.0.0] - 2026-09-21
+
+### 破坏性变更
+
+- 移除 Tailwind。`styles.css` 只含 `--rs-*` token、reset 与组件样式；宿主不再需要 `@tailwindcss/vite`。若业务自己写了工具类，在宿主 CSS 里自行引入 Tailwind。
+- 源码按组件分目录：`src/components/{name}/`。表格引擎从 `composables/` 并入 `src/components/table/`。样式源码为 `src/styles/index.css`。
+- 去掉 `exports["./*"]`。只从包根具名导入，不要 `niuma-ui/components/...`。
+- 1.x 维护线见 Git 分支 `1.x`（含 Tailwind 透传约定）。
+
+### 迁移
+
+1. 继续 `import 'niuma-ui/styles.css'`。
+2. 若只为展开本包才装 `@tailwindcss/vite`，可以卸掉。
+3. 深路径导入改回 `import { RsButton } from 'niuma-ui'`。
+4. 仍要 1.3.x 行为请装 `niuma-ui@1` 或跟踪 `1.x` 分支。
+
+## [1.3.9] - 2026-09-21
+
+### 新增
+
+- `RsAnchor`：页内目录。滚动容器可注入、墨点跟随、嵌套标题；Hash 路由设 `changeHash=false`。
+
+### 文档
+
+- 新增 `site/` 文档站（何时使用、代码演示、API、Design Token）。GitHub Pages 部署 `pnpm build:site`。`playground/` 仅内部测试，`pnpm dev` 不变。
+- `docs/components.md` 补为维护者架构契约（红线、公开面分层、Token / Vue / 浮层 / 表单 / a11y / SSR、新增检查清单）；英文 `docs/components.en.md`。`CONTRIBUTING.md` 改为 site 优先，playground 不能代替文档站。
+- `docs/components.en.md` 含完整组件清单；新增 `docs/consumers.en.md`；规范写明第三语言与 RTL 扩展步骤。中英清单必须同 PR 更新。
+- README / 接入指南按消费方改写：用户页不写发版密钥；版本统一 1.3.8；快速开始可复制；`consumers.md` 与英文同步。发版步骤只留在 `CONTRIBUTING.md` / `CONTRIBUTING.en.md`。
+- npm `description` 改为英文；`homepage` 指向文档站。`SECURITY.md` 中英并列。文档站指南页随 locale 切换英文正文。
+- 架构契约写明外部规范范围：尽量遵守 WHATWG HTML、Vue Style Guide A/B、WAI-ARIA APG；Google HTML/CSS Style Guide 不作合同。冲突时语义 > APG 键盘 > Vue 风格。
+- 明确 `playground/` 仅为内部冒烟与像素回归；对外用法只认 `site/` 文档站。playground 首页不再写安装教程。
+
 ## [1.3.8] - 2026-09-17
 
 ### 修复

package/NOTICE

@@ -9,17 +9,20 @@ See the LICENSE file for the full license text.
 
 ----
 
+Third-party dependencies are distributed under their own licenses.
+Versions below are typical; the lockfile is authoritative.
+
 第三方依赖按其各自许可证分发，常见依赖如下（请以 lockfile 中的实际版本为准）：
 
-| 项目 | 常见许可证 | 用途 |
-|------|------------|------|
-| Vue | MIT | peer 框架 |
-| Reka UI | MIT | 无障碍交互原语 |
-| Lucide (@lucide/vue) | ISC | 默认图标 |
+| Project / 项目 | Typical license / 常见许可证 | Use / 用途 |
+|----------------|------------------------------|------------|
+| Vue | MIT | peer framework |
+| Reka UI | MIT | accessible primitives |
+| Lucide (@lucide/vue) | ISC | default icons |
 | Monaco Editor | MIT | RsMonacoEditor |
 | CodeMirror | MIT | RsCodeEditor |
 | xterm.js (@xterm/xterm) | MIT | RsTerminal |
-| marked | MIT | Markdown 解析 |
-| DOMPurify | Apache-2.0 / MPL-2.0 | HTML 消毒 |
-| dayjs | MIT | 日期辅助 |
-| vue-sonner | MIT | Toast 原语 |
+| marked | MIT | Markdown parse |
+| DOMPurify | Apache-2.0 / MPL-2.0 | HTML sanitize |
+| dayjs | MIT | date helpers |
+| vue-sonner | MIT | toast primitive |

package/README.en.md

@@ -1,35 +1,35 @@
 # niuma-ui
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
+[![npm](https://img.shields.io/npm/v/niuma-ui.svg)](https://www.npmjs.com/package/niuma-ui)
 [![Vue 3](https://img.shields.io/badge/Vue-3.5+-42b883.svg)](https://vuejs.org/)
 [![Node](https://img.shields.io/badge/Node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
-[![pnpm](https://img.shields.io/badge/pnpm-%3E%3D9-yellow.svg)](https://pnpm.io/)
 
 English | [简体中文](./README.md)
 
-Vue 3 **workbench** design system: `Rs*` components, `--rs-*` tokens, and optional editor / terminal wrappers.
+Vue 3 **workbench** design system: consistent `Rs*` components, `--rs-*` tokens, and optional editor / terminal wrappers.
 
-Built for ops consoles, database workbenches, and internal admin UIs. Marketing sites can use named imports, but this is not a lightweight Ant Design-style kit — `npm install` pulls Monaco, CodeMirror, and xterm.
+Built for ops consoles, database workbenches, and internal admin UIs. Marketing sites can use named imports. `npm install` pulls Monaco, CodeMirror, and xterm; named imports control the bundle.
 
-**Status:** open source from **v1.0.0** under [Apache License 2.0](./LICENSE). From **v1.2.0** the npm package is compiled ESM (`install` then import by package name).
+**Status:** [Apache License 2.0](./LICENSE) since v1.0.0. Compiled ESM on npm since v1.2.0. Current line is **2.0.0**. The `1.x` branch keeps the 1.3 line.
 
 ## Features
 
-- **Design tokens** — light / dark via `data-rs-theme` and CSS variables; hosts can override a brand layer
-- **Rs\* components** — Button, Form, Dialog, Table, Tree, Tabs, and more
-- **Tooling-oriented** — Monaco, CodeMirror, xterm wrappers (import carefully in light apps)
-- **Accessible primitives** — built on [Reka UI](https://reka-ui.com/); apps only consume `niuma-ui`
-- **Vite-friendly** — `import { RsButton } from 'niuma-ui'` is the public API; `niumaUiHost` is serve-only HMR
+- **Design tokens** — light / dark via `data-rs-theme` and CSS variables; hosts override a brand layer
+- **Rs\* components** — Button, Form, Dialog, Table, Tree, Tabs, Anchor, and more
+- **Tooling** — Monaco, CodeMirror, xterm (import only on routes that need them)
+- **Accessibility** — [Reka UI](https://reka-ui.com/) underneath; apps depend only on `niuma-ui`
+- **Vite** — `import { RsButton } from 'niuma-ui'` is enough to bundle; `niumaUiHost` is local `pnpm dev` HMR only
 
 ## Requirements
 
 | Item | Version |
 |------|---------|
 | Node.js | ≥ 20 |
-| Package manager | npm / pnpm / yarn (this repo develops with pnpm) |
+| Package manager | npm / pnpm / yarn (this repo develops with pnpm ≥ 9) |
 | Vue | ^3.5 (`peerDependency`) |
 | Bundler | Vite 5+ recommended; `RsMonacoEditor` needs Vite `?worker` |
-| Styles | `import 'niuma-ui/styles.css'` passes through `@import 'tailwindcss'`; Vite hosts need `@tailwindcss/vite` |
+| Styles | `import 'niuma-ui/styles.css'` (standalone CSS, no Tailwind) |
 
 ## Install
 
@@ -38,19 +38,15 @@ pnpm add niuma-ui
 # or: npm install niuma-ui / yarn add niuma-ui
 ```
 
-Pin a version:
+Prefer a range such as `^2.0.0`. Pin **2.0.0** for a bit-for-bit install. Use `niuma-ui@1` for the 1.x line.
 
-```bash
-pnpm add niuma-ui@1.2.0
-```
-
-Local link and Vite details: **[Consumer guide](./docs/consumers.md)** (Chinese).
+Local `link`, Vite plugins, and bundle size: **[Consumer guide](./docs/consumers.en.md)** ([中文](./docs/consumers.md)).
 
 ## Quick start
 
 ```ts
+// main.ts
 import { createApp } from 'vue'
-import { RsConfigProvider, RsButton } from 'niuma-ui'
 import 'niuma-ui/styles.css'
 import App from './App.vue'
 
@@ -58,45 +54,67 @@ createApp(App).mount('#app')
 ```
 
 ```vue
+<!-- App.vue -->
 <script setup lang="ts">
 import { RsConfigProvider, RsButton } from 'niuma-ui'
 </script>
 
 <template>
-  <RsConfigProvider theme="light" locale="zh-CN">
+  <RsConfigProvider theme="light" locale="en-US">
     <RsButton variant="primary">Hello</RsButton>
   </RsConfigProvider>
 </template>
 ```
 
-## Usage conventions
+Shipped locales: `zh-CN` | `en-US`.
+
+## Usage
 
-1. Apps import only from `niuma-ui` — **do not** depend on `reka-ui` directly.
-2. Styles: `import 'niuma-ui/styles.css'`.
-3. Wrap the app with `RsConfigProvider`.
-4. Light apps should named-import and wrap what they need — do not `import *`. Install still includes editor dependencies; tree-shaking only affects the bundle.
+1. Named-import from the package root only. **Do not** depend on `reka-ui`. Do not `import *`.
+2. Import `niuma-ui/styles.css` once, then your brand CSS.
+3. Wrap the app with `RsConfigProvider` (theme, locale, default control size).
+4. Light sites re-export used symbols from their own `ui.ts`. Do not alias the package to this repo’s `src/index.ts`.
 
-Component catalog: **[docs/components.md](./docs/components.md)**.
+Component APIs live on the docs site. The architecture contract is for maintainers: [components.en.md](./docs/components.en.md) ([中文](./docs/components.md)).
 
-## Live demos
+## Docs
 
-- **Component site**: [https://blair-shang.github.io/niuma-ui/](https://blair-shang.github.io/niuma-ui/) (GitHub Pages, deploys from `main`)
-- Local: `pnpm dev` → http://localhost:5180
+- **Component site:** [https://blair-shang.github.io/niuma-ui/](https://blair-shang.github.io/niuma-ui/) (source: `site/`)
+- Local docs: `pnpm dev:site` → http://127.0.0.1:5181
+- `playground/` is internal smoke / visual regression only (`pnpm dev` → :5180). It is not usage documentation.
+
+| Doc | Audience |
+|-----|----------|
+| [docs/consumers.en.md](./docs/consumers.en.md) | People installing the library ([中文](./docs/consumers.md)) |
+| [docs/components.en.md](./docs/components.en.md) | People changing this repository ([中文](./docs/components.md)) |
+| [CONTRIBUTING.en.md](./CONTRIBUTING.en.md) | PRs, tests, releases ([中文](./CONTRIBUTING.md)) |
+| [CHANGELOG.md](./CHANGELOG.md) | Release notes |
+| [SECURITY.md](./SECURITY.md) | Private vulnerability reports |
 
 ## Local development
 
 ```bash
 pnpm install
-pnpm dev
-pnpm build               # library → dist/ (npm publish)
-pnpm build:playground
+pnpm dev:site     # docs site
 pnpm test
+pnpm build        # library → dist/
 ```
 
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full contributor flow.
+
 ## Versioning
 
-Semantic Versioning. Stable publishes set the npm dist-tag **`latest`** (prereleases use `next`). There is no GitHub tag named `latest`. Pin a SemVer tag for reproducible releases. See [CHANGELOG.md](./CHANGELOG.md).
+[Semantic Versioning](https://semver.org/): compatible fixes are PATCH, compatible features MINOR, breaking API or token renames MAJOR.
+
+Stable publishes set npm dist-tag **`latest`**; prereleases use **`next`**. There is no Git tag named `latest`. Release steps live only in [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License and credits
+
+[Apache License 2.0](./LICENSE). Attribution: [NOTICE](./NOTICE).
 
-## License
+Primitives: [Reka UI](https://reka-ui.com/). Icons: [Lucide](https://lucide.dev/). Editors: [Monaco](https://microsoft.github.io/monaco-editor/), [CodeMirror](https://codemirror.net/). Terminal: [xterm.js](https://xtermjs.org/).
 
-[Apache License 2.0](./LICENSE). See [NOTICE](./NOTICE) for attribution.
+- Docs: https://blair-shang.github.io/niuma-ui/
+- npm: https://www.npmjs.com/package/niuma-ui
+- Source: https://github.com/Blair-Shang/niuma-ui
+- Issues: https://github.com/Blair-Shang/niuma-ui/issues

package/README.md

@@ -1,60 +1,52 @@
 # niuma-ui
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
+[![npm](https://img.shields.io/npm/v/niuma-ui.svg)](https://www.npmjs.com/package/niuma-ui)
 [![Vue 3](https://img.shields.io/badge/Vue-3.5+-42b883.svg)](https://vuejs.org/)
 [![Node](https://img.shields.io/badge/Node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
-[![pnpm](https://img.shields.io/badge/pnpm-%3E%3D9-yellow.svg)](https://pnpm.io/)
 
 [English](./README.en.md) | 简体中文
 
-Vue 3 **工作台**设计系统：一致的 `Rs*` 组件、`--rs-*` token，以及面向桌面工具的编辑器 / 终端封装。
+Vue 3 **工作台**设计系统：一致的 `Rs*` 组件与 `--rs-*` Token，以及按需使用的编辑器 / 终端封装。
 
-适用于运维控制台、数据库工作台、内部后台。营销站 / 落地页也可以用，但请具名导入；本包不是 Ant Design 那种轻量通用库，`npm install` 会带上 Monaco、CodeMirror、xterm。
+适用于运维控制台、数据库工作台、内部后台。营销站也可以用具名导入。`npm install` 会带上 Monaco、CodeMirror、xterm，体积靠具名导入摇树。
 
-**状态：** 自 **v1.0.0** 起按 [Apache License 2.0](./LICENSE) 开源。自 **v1.2.0** 起 npm 发布编译后的 ESM（`install` 后按包名导入即可）。
+**状态：** [Apache License 2.0](./LICENSE)，自 v1.0.0 开源。自 v1.2.0 起 npm 发布编译 ESM。当前主线 **2.0.0**。1.x 见分支 `1.x`。
 
 ## 特性
 
-- **设计 token**：明暗主题通过 `data-rs-theme` 与 CSS 变量驱动，业务侧可用品牌层覆盖
-- **Rs\* 组件**：Button、Form、Dialog、Table、Tree、Tabs 等完整交互控件
-- **专业工具向**：Monaco、CodeMirror、xterm 等编辑器 / 终端封装（按需引入）
-- **无障碍与焦点**：底层基于 [Reka UI](https://reka-ui.com/)，业务层只消费 `niuma-ui`
-- **Vite 友好**：`import { RsButton } from 'niuma-ui'` 即可打包；`niumaUiHost` 只服务本机 `pnpm dev` 联调源码
+- **Design Token**：明暗主题走 `data-rs-theme` 与 CSS 变量，宿主用品牌层覆盖
+- **Rs\* 组件**：Button、Form、Dialog、Table、Tree、Tabs、Anchor 等
+- **专业工具**：Monaco、CodeMirror、xterm（只在用到的路由引入）
+- **无障碍**：底层 [Reka UI](https://reka-ui.com/)，应用只依赖 `niuma-ui`
+- **Vite**：`import { RsButton } from 'niuma-ui'` 即可打包；`niumaUiHost` 仅本机 `pnpm dev` 联调源码
 
 ## 要求
 
 | 项 | 版本 |
 |----|------|
 | Node.js | ≥ 20 |
-| 包管理器 | npm / pnpm / yarn（本仓库开发用 pnpm） |
-| Vue | ^3.5.0（peerDependency） |
-| 打包器 | Vite 5+ 推荐；使用 `RsMonacoEditor` 时需要 Vite 处理 `?worker` |
-| 样式 | `import 'niuma-ui/styles.css'`（透传 `@import 'tailwindcss'`）；Vite 宿主用 `@tailwindcss/vite` 处理 |
+| 包管理器 | npm / pnpm / yarn（本仓库开发用 pnpm ≥ 9） |
+| Vue | ^3.5（peerDependency） |
+| 打包器 | 推荐 Vite 5+；`RsMonacoEditor` 需要 Vite 处理 `?worker` |
+| 样式 | `import 'niuma-ui/styles.css'`（独立 CSS，不含 Tailwind） |
 
 ## 安装
 
 ```bash
 pnpm add niuma-ui
 # 或 npm install niuma-ui / yarn add niuma-ui
-# 业务流水线跟最新正式版（npm dist-tag latest，无 GitHub 标签 latest）
-pnpm add niuma-ui@latest
 ```
 
-钉死某一版：
+建议锁定兼容范围，例如 `^2.0.0`。精确复现请钉死 **2.0.0**。1.x 请用 `niuma-ui@1`。
 
-```bash
-pnpm add niuma-ui@1.2.0
-# 或
-pnpm add git+https://github.com/Blair-Shang/niuma-ui.git#v1.2.0
-```
-
-本地 link、Vite 配置、包体积建议见 **[消费方指南](./docs/consumers.md)**。
+本地改源码、Vite 插件、包体积见 **[消费方指南](./docs/consumers.md)**（[English](./docs/consumers.en.md)）。
 
 ## 快速开始
 
 ```ts
+// main.ts
 import { createApp } from 'vue'
-import { RsConfigProvider, RsButton } from 'niuma-ui'
 import 'niuma-ui/styles.css'
 import App from './App.vue'
 
@@ -62,6 +54,7 @@ createApp(App).mount('#app')
 ```
 
 ```vue
+<!-- App.vue -->
 <script setup lang="ts">
 import { RsConfigProvider, RsButton } from 'niuma-ui'
 </script>
@@ -73,96 +66,61 @@ import { RsConfigProvider, RsButton } from 'niuma-ui'
 </template>
 ```
 
+`locale` 现支持 `zh-CN` | `en-US`。
+
 ## 使用约定
 
-1. 应用与业务模块只允许 `import { … } from 'niuma-ui'`，**禁止**直接依赖 `reka-ui`。
-2. 样式入口：`import 'niuma-ui/styles.css'`（须在业务品牌 CSS 之前或按文档顺序加载）。
-3. 根节点使用 `RsConfigProvider` 提供主题、语言与默认控件尺寸。
-4. 从主入口具名导入；轻量宿主在自己的 `ui.ts` 里再导出。启用 `niumaUiHost`，不要 `import *`，也不要把主入口别名到 `src/index.ts`。
+1. 只从包根具名导入：`import { RsButton } from 'niuma-ui'`。**不要**直接依赖 `reka-ui`，不要 `import *`。
+2. 样式只引一次 `niuma-ui/styles.css`，再加载你的品牌 CSS。
+3. 根节点包 `RsConfigProvider`（主题、语言、默认控件尺寸）。
+4. 轻量站点在自己的 `ui.ts` 里再导出用到的符号。不要把包名别名到本仓库的 `src/index.ts`。
+
+组件 API 以文档站为准。仓库里的架构契约给维护者：[组件规范](./docs/components.md)（[English](./docs/components.en.md)）。
 
-组件清单与新增组件规范见 **[组件说明](./docs/components.md)**。
+## 文档
 
-## 在线演示
+- **组件文档（官网）**：[https://blair-shang.github.io/niuma-ui/](https://blair-shang.github.io/niuma-ui/)（源码 `site/`）
+- 本地文档站：`pnpm dev:site` → http://127.0.0.1:5181
+- `playground/` 仅内部冒烟与像素回归（`pnpm dev` → :5180），不提供对外用法
 
-- **组件演示站**：[https://blair-shang.github.io/niuma-ui/](https://blair-shang.github.io/niuma-ui/)（随 `main` 由 [pages.yml](./.github/workflows/pages.yml) 部署）
-- 首次启用：仓库 **Settings → Pages → Source** 选 **GitHub Actions**
-- 本地：`pnpm dev` → http://localhost:5180
+| 文档 | 给谁看 |
+|------|--------|
+| [docs/consumers.md](./docs/consumers.md) | 把库装进产品的人（[English](./docs/consumers.en.md)） |
+| [docs/components.md](./docs/components.md) | 改本仓库的人（[English](./docs/components.en.md)） |
+| [CONTRIBUTING.md](./CONTRIBUTING.md) | PR、测试、发版（[English](./CONTRIBUTING.en.md)） |
+| [CHANGELOG.md](./CHANGELOG.md) | 版本记录 |
+| [SECURITY.md](./SECURITY.md) | 漏洞私下报告 |
 
 ## 本地开发
 
 ```bash
 pnpm install
-pnpm dev                 # 组件演示，默认 http://localhost:5180
-pnpm build               # 库产物 → dist/（npm 发布）
-pnpm build:playground    # 构建演示站静态资源 → playground-dist/
-pnpm test                # Vitest
-pnpm test:watch
+pnpm dev:site     # 文档站
+pnpm test         # Vitest
+pnpm build        # 库 → dist/
 ```
 
-| 路径 | 说明 |
-|------|------|
-| `src/components/` | `Rs*` 组件实现 |
-| `src/styles.css` | Token 与全局样式 |
-| `src/theme/` | 主题应用与品牌覆盖示例 |
-| `src/monaco/` | Monaco 语言与 Worker 辅助 |
-| `playground/` | 组件演示应用（对外演示门面） |
-| `vite-plugins/` | 可供宿主工程复用的 Vite 插件 |
-| `docs/` | 接入与组件类文档 |
-
-## 版本与发版
+贡献步骤见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
 
-遵循 [Semantic Versioning](https://semver.org/)：
+## 版本
 
-| 变更类型 | 版本 |
-|----------|------|
-| 缺陷修复、文档（兼容） | PATCH `1.0.x` |
-| 新增组件 / 能力（兼容） | MINOR `1.x.0` |
-| 破坏性 API 或 token 更名 | MAJOR `x.0.0` |
+遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)：
 
-```bash
-# 1. 更新 package.json 的 version
-# 2. 更新 CHANGELOG.md
-# 3. 提交并推送 main 后打 tag（推送 tag 会触发 Publish 流水线自动 pnpm publish）
-git tag v1.0.1
-git push origin v1.0.1
-```
-
-需在仓库 Settings → Secrets 配置 **`NPM_TOKEN`**：
-
-1. 打开 https://www.npmjs.com/settings/shangjian/tokens → **Generate New Token** → **Granular Access Token**
-2. Permissions：对包 `niuma-ui` 勾选 **Read and write**
-3. 务必开启 **Bypass two-factor authentication**（否则 CI 会报 `EOTP`）
-4. 把 token 填进 GitHub Secret 名 `NPM_TOKEN`
-
-不要配置 `NPM_OTP`：一次性验证码约 30 秒过期，无法用于自动发版。
+| 变更 | 版本 |
+|------|------|
+| 兼容的缺陷 / 文档 | PATCH |
+| 兼容的新组件 / 能力 | MINOR |
+| 破坏性 API 或 Token 更名 | MAJOR |
 
-也可在 Actions 里手动运行 **Publish** 工作流。
+正式版更新 npm dist-tag **`latest`**，预发布走 **`next`**。没有名为 `latest` 的 Git 标签。发版流程只在 [CONTRIBUTING.md](./CONTRIBUTING.md)，不在本页。
 
-正式版会更新 npm dist-tag **`latest`**（`niuma-ui@latest`），不维护 GitHub 标签 `latest`。可复现发版请钉 SemVer tag；预发布走 npm tag `next`。
+## 许可与致谢
 
-详见 [CHANGELOG.md](./CHANGELOG.md)。
+[Apache License 2.0](./LICENSE)。版权与第三方声明见 [NOTICE](./NOTICE)。
 
-## 相关文档
+交互原语：[Reka UI](https://reka-ui.com/)。图标：[Lucide](https://lucide.dev/)。编辑器：[Monaco](https://microsoft.github.io/monaco-editor/)、[CodeMirror](https://codemirror.net/)。终端：[xterm.js](https://xtermjs.org/)。
 
-| 文档 | 内容 |
-|------|------|
-| [docs/consumers.md](./docs/consumers.md) | 宿主工程接入、联调、CI、体积与插件 |
-| [docs/components.md](./docs/components.md) | 公开组件清单与设计约定 |
-| [CONTRIBUTING.md](./CONTRIBUTING.md) | 贡献指南 |
-| [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) | 行为准则 |
-| [SECURITY.md](./SECURITY.md) | 安全漏洞报告 |
-| [NOTICE](./NOTICE) | Apache 版权与第三方声明 |
-| [README.en.md](./README.en.md) | English README |
-| [src/theme/brand.example.css](./src/theme/brand.example.css) | 品牌色覆盖示例 |
-
-## 仓库信息
-
-- **包名**：`niuma-ui`
-- **源码**：https://github.com/Blair-Shang/niuma-ui
-- **Issues**：https://github.com/Blair-Shang/niuma-ui/issues
-- **开源基线**：`v1.0.0`
-- **许可**：[Apache License 2.0](./LICENSE)
-
-## 致谢
-
-交互原语基于 [Reka UI](https://reka-ui.com/)；图标默认集成 [Lucide](https://lucide.dev/)；代码编辑能力基于 [Monaco Editor](https://microsoft.github.io/monaco-editor/) 与 [CodeMirror](https://codemirror.net/)；终端基于 [xterm.js](https://xtermjs.org/)。
+- 文档站：https://blair-shang.github.io/niuma-ui/
+- npm：https://www.npmjs.com/package/niuma-ui
+- 源码：https://github.com/Blair-Shang/niuma-ui
+- Issues：https://github.com/Blair-Shang/niuma-ui/issues

package/dist/components/_shared/index.d.ts

@@ -0,0 +1,4 @@
+export type { RsFeedbackTone, RsToastPosition, RsToastType, RsOverlayAnchorBox, RsOverlayBox } from './src/overlay-utils';
+export { RS_TOAST_DEFAULT_GAP, RS_TOAST_DEFAULT_POSITION, rsToastPositions, rsFeedbackIconClass, placeAnchoredPopup, stepEnabledIndex } from './src/overlay-utils';
+export { useResolvedRsComponentSize, resolveRsComponentSize } from './src/resolve-size';
+export { useResolvedRsRadius, rsRadiusCss } from './src/resolve-radius';

package/dist/components/_shared/src/overlay-utils.js

@@ -0,0 +1,45 @@
+//#region src/components/_shared/src/overlay-utils.ts
+var RS_TOAST_DEFAULT_POSITION = "top-center";
+/** 多条 Toast 之间的垂直间距（px），传给 vue-sonner `gap` */
+var RS_TOAST_DEFAULT_GAP = 4;
+var rsToastPositions = [
+	"top-center",
+	"top-left",
+	"top-right",
+	"bottom-center",
+	"bottom-left",
+	"bottom-right"
+];
+function rsFeedbackIconClass(tone) {
+	return `rs-feedback-icon rs-feedback-icon--${tone}`;
+}
+/**
+* 把浮层贴到锚点：优先下方，视口不够则翻到上方，左右夹进窗口。
+* 对齐 WAI-ARIA APG 浮层惯例与 CSS overflow 避让，不跟某一家组件库的 API。
+*/
+function placeAnchoredPopup(anchor, popup, viewport, gap = 4) {
+	const below = anchor.top + anchor.height + gap;
+	const above = anchor.top - popup.height - gap;
+	const placement = below + popup.height <= viewport.height || above < gap ? "bottom" : "top";
+	const top = placement === "bottom" ? below : Math.max(gap, above);
+	const width = Math.min(popup.width, Math.max(0, viewport.width - gap * 2));
+	const maxLeft = Math.max(gap, viewport.width - width - gap);
+	return {
+		top,
+		left: Math.min(Math.max(gap, anchor.left), maxLeft),
+		width,
+		placement
+	};
+}
+/** 在可选项里按方向跳过 disabled，供 combobox / listbox 方向键与 Home / End。 */
+function stepEnabledIndex(options, current, delta) {
+	if (!options.length) return 0;
+	let index = current;
+	for (let n = 0; n < options.length; n += 1) {
+		index = (index + delta + options.length) % options.length;
+		if (!options[index]?.disabled) return index;
+	}
+	return Math.max(0, current);
+}
+//#endregion
+export { RS_TOAST_DEFAULT_GAP, RS_TOAST_DEFAULT_POSITION, placeAnchoredPopup, rsFeedbackIconClass, rsToastPositions, stepEnabledIndex };

package/dist/components/_shared/src/resolve-radius.d.ts

@@ -0,0 +1,9 @@
+import { type ComputedRef } from 'vue';
+import { type RsRadius } from '../../../theme/types';
+/**
+ * 解析圆角：props → ConfigProvider.controlRadius → 组件默认档。
+ * 业务应传 `radius` / `iconRadius` 或依赖全局配置，避免 :deep 改 border-radius。
+ */
+export declare function useResolvedRsRadius(radius: () => RsRadius | undefined, fallback: RsRadius): ComputedRef<RsRadius>;
+/** 将档位转为可写入 style / CSS 变量的值。 */
+export declare function rsRadiusCss(radius: RsRadius): string;

package/dist/components/_shared/src/resolve-radius.js

@@ -0,0 +1,18 @@
+import { useRsConfigOptional } from "../../../composables/useRsConfig.js";
+import { RS_RADIUS_CSS } from "../../../theme/types.js";
+import { computed } from "vue";
+//#region src/components/_shared/src/resolve-radius.ts
+/**
+* 解析圆角：props → ConfigProvider.controlRadius → 组件默认档。
+* 业务应传 `radius` / `iconRadius` 或依赖全局配置，避免 :deep 改 border-radius。
+*/
+function useResolvedRsRadius(radius, fallback) {
+	const config = useRsConfigOptional();
+	return computed(() => radius() ?? config?.controlRadius.value ?? fallback);
+}
+/** 将档位转为可写入 style / CSS 变量的值。 */
+function rsRadiusCss(radius) {
+	return RS_RADIUS_CSS[radius];
+}
+//#endregion
+export { rsRadiusCss, useResolvedRsRadius };

package/dist/components/_shared/src/resolve-size.d.ts

@@ -0,0 +1,10 @@
+import { type ComputedRef } from 'vue';
+import type { RsComponentSize } from '../../../theme/types';
+import { type RsFormContext } from '../../form/src/form-utils';
+/**
+ * 解析控件尺寸：props → Form → ConfigProvider → md。
+ * 业务应传 `size` 或依赖全局/表单上下文，避免 :deep 改高度。
+ */
+export declare function resolveRsComponentSize(size: RsComponentSize | undefined, form?: RsFormContext | null): ComputedRef<RsComponentSize>;
+/** 在 setup 内便捷解析（自动读 Form / Config）。 */
+export declare function useResolvedRsComponentSize(size: () => RsComponentSize | undefined): ComputedRef<RsComponentSize>;

package/dist/components/_shared/src/resolve-size.js

@@ -0,0 +1,20 @@
+import { useRsConfigOptional } from "../../../composables/useRsConfig.js";
+import { useRsFormContext } from "../../form/src/form-utils.js";
+import { computed } from "vue";
+//#region src/components/_shared/src/resolve-size.ts
+/**
+* 解析控件尺寸：props → Form → ConfigProvider → md。
+* 业务应传 `size` 或依赖全局/表单上下文，避免 :deep 改高度。
+*/
+function resolveRsComponentSize(size, form) {
+	const config = useRsConfigOptional();
+	return computed(() => size ?? form?.size.value ?? config?.controlSize.value ?? "md");
+}
+/** 在 setup 内便捷解析（自动读 Form / Config）。 */
+function useResolvedRsComponentSize(size) {
+	const form = useRsFormContext();
+	const config = useRsConfigOptional();
+	return computed(() => size() ?? form?.size.value ?? config?.controlSize.value ?? "md");
+}
+//#endregion
+export { resolveRsComponentSize, useResolvedRsComponentSize };

package/dist/components/alert/index.d.ts

@@ -0,0 +1 @@
+export { default as RsAlert } from './src/RsAlert.js';