@svp-chain-sdk/ui 0.1.3

package/README.md

@@ -0,0 +1,276 @@
+# `@svp-chain-sdk/ui` Tailwind Provider 使用指南
+
+## 1. 适用范围
+
+`@svp-chain-sdk/ui` 当前的主要接入方式是 Tailwind provider：消费方把 `@svp-chain-sdk/ui/tailwind` 注册为 Tailwind 插件，然后直接在 HTML、React、Vue 或其他模板中组合 `.ui-button` 等 CSS class。
+
+这是**框架无关、非 React 组件优先**的模式。包根入口仍提供可选的 React `Button`、`buttonVariants` 和 `cn`，也导出 `@svp-chain-sdk/ui/styles.css` 样式入口，但它们不是本文的主要接入方式。目前 Tailwind provider 只注册按钮相关 class，不应假定它包含表单、弹窗或其他尚未实现的组件。
+
+## 2. 从公共 npm registry 安装
+
+该包以 npm 默认的公共 registry 为标准安装来源，无需额外指定 registry：
+
+```sh
+npm install @svp-chain-sdk/ui
+```
+
+消费方还需要使用 Tailwind CSS；该包的 provider 构建自 Tailwind v4，目前包本身不会把 `tailwindcss` 作为运行时依赖安装到消费项目中。
+
+## 3. 注册 Tailwind provider
+
+在消费项目的 Tailwind 配置中引入默认导出，并且只注册一次：
+
+```ts
+// tailwind.config.ts（Tailwind v4 兼容配置）
+import svpUi from '@svp-chain-sdk/ui/tailwind'
+
+export default {
+  plugins: [svpUi],
+}
+```
+
+`@svp-chain-sdk/ui` 是 ESM-only 包，因此配置文件和构建工具必须支持 ESM `import`。注册后仍需由消费项目现有的 Tailwind 构建流程产出并加载 CSS。
+
+## 4. 使用示例
+
+所有样式变体都要和基础 class `.ui-button` 组合使用。单独写 `.ui-button-primary` 或 `.ui-button-danger` 只会得到颜色，不会得到布局、间距、焦点态和禁用态。
+
+### HTML
+
+```html
+<button type="button" class="ui-button ui-button-primary">
+  继续
+</button>
+
+<button type="button" class="ui-button ui-button-danger" disabled>
+  删除
+</button>
+```
+
+### React
+
+这里使用原生元素和 `className`，不依赖包根入口的 React `Button`：
+
+```tsx
+export function Actions() {
+  return (
+    <div>
+      <button type="button" className="ui-button ui-button-primary">
+        继续
+      </button>
+      <button type="button" className="ui-button ui-button-danger">
+        删除
+      </button>
+    </div>
+  )
+}
+```
+
+### Vue
+
+```vue
+<template>
+  <div>
+    <button type="button" class="ui-button ui-button-primary" @click="submit">
+      继续
+    </button>
+    <button type="button" class="ui-button ui-button-danger" :disabled="pending">
+      删除
+    </button>
+  </div>
+</template>
+
+<script setup lang="ts">
+const pending = false
+function submit() {
+  // 业务逻辑
+}
+</script>
+```
+
+## 5. 现有 class 与组合规则
+
+| Class / 状态 | 用途 | 组合规则 |
+| --- | --- | --- |
+| `.ui-button` | 按钮基础布局、尺寸、字体、过渡、键盘焦点态和原生禁用态 | 每个按钮都应使用 |
+| `.ui-button-primary` | 主操作背景色、前景色和 hover 色 | 与 `.ui-button` 一起使用 |
+| `.ui-button-danger` | 危险操作背景色、前景色和 hover 色 | 与 `.ui-button` 一起使用 |
+| `.ui-button:focus-visible` | 键盘等触发的可见焦点轮廓 | 由基础 class 自动提供 |
+| `.ui-button:disabled` | 禁止指针事件并降低透明度 | 只匹配支持 `disabled` 的元素及其真实禁用状态 |
+| `.ui-button-primary:hover` | 主操作 hover 背景色 | 由 primary class 自动提供 |
+| `.ui-button-danger:hover` | 危险操作 hover 背景色 | 由 danger class 自动提供 |
+
+当前没有 `secondary`、`outline`、`ghost`、尺寸或 loading 等 provider class。不能把可选 React `buttonVariants` 所支持的变体当作 provider class 使用。
+
+## 6. 完整样式属性表
+
+下表逐项列出 provider 当前注册的样式，数值与源码保持一致。
+
+| 选择器 | CSS 属性 | 值 |
+| --- | --- | --- |
+| `.ui-button` | `display` | `inline-flex` |
+| `.ui-button` | `align-items` | `center` |
+| `.ui-button` | `justify-content` | `center` |
+| `.ui-button` | `gap` | `0.5rem` |
+| `.ui-button` | `white-space` | `nowrap` |
+| `.ui-button` | `border-radius` | `0.375rem` |
+| `.ui-button` | `padding` | `0.5rem 1rem` |
+| `.ui-button` | `font-size` | `0.875rem` |
+| `.ui-button` | `line-height` | `1.25rem` |
+| `.ui-button` | `font-weight` | `500` |
+| `.ui-button` | `transition` | `background-color 150ms, color 150ms, border-color 150ms, opacity 150ms` |
+| `.ui-button:focus-visible` | `outline` | `2px solid var(--color-ring, #159bb5)` |
+| `.ui-button:focus-visible` | `outline-offset` | `2px` |
+| `.ui-button:disabled` | `pointer-events` | `none` |
+| `.ui-button:disabled` | `opacity` | `0.5` |
+| `.ui-button-primary` | `background-color` | `var(--color-primary, #159bb5)` |
+| `.ui-button-primary` | `color` | `var(--color-primary-foreground, white)` |
+| `.ui-button-primary:hover` | `background-color` | `color-mix(in srgb, var(--color-primary, #159bb5) 90%, transparent)` |
+| `.ui-button-danger` | `background-color` | `var(--color-destructive, #e5484d)` |
+| `.ui-button-danger` | `color` | `var(--color-destructive-foreground, white)` |
+| `.ui-button-danger:hover` | `background-color` | `color-mix(in srgb, var(--color-destructive, #e5484d) 90%, transparent)` |
+
+默认插件还通过 Tailwind `addBase` 注册：
+
+```css
+:root {
+  --svp-ui-brand: #159bb5;
+}
+```
+
+该变量目前仅被注册，现有按钮规则没有引用它。按钮实际读取的是下一节中的五个 `--color-*` 变量。
+
+## 7. 用 CSS variables 自定义主题
+
+在消费项目加载的 CSS 中覆盖变量即可，无需复制组件定义：
+
+```css
+:root {
+  --color-primary: #006adc;
+  --color-primary-foreground: white;
+  --color-destructive: #d13415;
+  --color-destructive-foreground: white;
+  --color-ring: #006adc;
+}
+```
+
+| 变量 | 使用位置 | 未设置时的 fallback |
+| --- | --- | --- |
+| `--color-primary` | primary 背景、primary hover 混色 | `#159bb5` |
+| `--color-primary-foreground` | primary 文本 | `white` |
+| `--color-destructive` | danger 背景、danger hover 混色 | `#e5484d` |
+| `--color-destructive-foreground` | danger 文本 | `white` |
+| `--color-ring` | `focus-visible` 轮廓 | `#159bb5` |
+
+变量遵循普通 CSS 级联规则，也可以在某个容器上覆盖以实现局部主题。hover 使用 CSS `color-mix()`；目标浏览器需要支持该能力。
+
+## 8. 扩展自定义 plugin
+
+`@svp-chain-sdk/ui/tailwind` 提供两个具名导出：
+
+- `uiButtonComponents`：当前按钮组件配置对象。
+- `uiComponents`：默认插件注册的完整组件配置；当前它与 `uiButtonComponents` 是同一个对象。未来若增加其他组件，应优先使用 `uiComponents` 来继承完整配置。
+
+如需在同一个插件中加入应用级 class，可组合 `uiComponents`：
+
+```ts
+import plugin from 'tailwindcss/plugin'
+import { uiComponents } from '@svp-chain-sdk/ui/tailwind'
+
+const appUi = plugin(({ addComponents }) => {
+  addComponents(uiComponents)
+  addComponents({
+    '.app-toolbar-button': {
+      padding: '0.375rem 0.75rem',
+    },
+  })
+})
+
+export default {
+  plugins: [appUi],
+}
+```
+
+只想明确继承按钮配置时，也可以把上例中的 `uiComponents` 换成 `uiButtonComponents`。
+
+默认插件与导出的配置对象来自同一份组件定义。请在以下两种方式中二选一，避免重复注册：
+
+1. `plugins: [svpUi]`；或
+2. 自定义 plugin 中 `addComponents(uiComponents)`。
+
+注意：第二种方式只加入组件规则，不会自动加入默认插件通过 `addBase` 设置的 `--svp-ui-brand`。由于现有按钮规则未使用该变量，这不影响当前按钮样式；如果应用依赖该变量，应自行在 CSS 或自定义 plugin 中声明。
+
+## 9. 常见问题
+
+### class 写了但样式不生效
+
+依次检查：
+
+1. 已安装并能解析 `@svp-chain-sdk/ui/tailwind`。
+2. provider 已加入实际生效的 Tailwind 配置，且没有同时使用默认插件和自定义重复注册。
+3. Tailwind 构建流程已运行，产物 CSS 已被页面加载。
+4. 基础 class 与变体 class 已组合，例如 `ui-button ui-button-primary`。
+5. 消费项目的 CSS 是否以更高优先级覆盖了规则。
+6. 若不使用 provider，可改为导入 `@svp-chain-sdk/ui/styles.css`。它是包构建时从当前 Tailwind v4 样式入口生成并复制的 CSS，但不是 provider 按钮组件规则的替代品；不要假定导入它会生成 `.ui-button`、`.ui-button-primary` 或 `.ui-button-danger`。
+
+### 出现 CommonJS / `require()` 错误
+
+包的 `package.json` 声明了 `"type": "module"`，根入口和 `./tailwind` export 只有 `import` 条件，没有 CommonJS `require` 条件。请使用 ESM：
+
+```ts
+import svpUi from '@svp-chain-sdk/ui/tailwind'
+```
+
+不要使用：
+
+```js
+const svpUi = require('@svp-chain-sdk/ui/tailwind')
+```
+
+如果工具默认把 `tailwind.config` 当作 CommonJS，请切换到它支持的 ESM 配置形式；具体文件名和配置取决于消费项目的构建工具。
+
+### 可以把 class 放在 `<div>` 上吗？
+
+视觉上可以，但 class 不会让 `<div>` 自动获得按钮语义、键盘操作或原生禁用行为。优先使用原生 `<button type="button">`。
+
+若业务确实必须使用 `<div>`，至少需要自行完整实现 `role="button"`、`tabindex="0"`、Enter/Space 键盘触发、禁用语义与事件拦截。尤其要注意 `.ui-button:disabled` 不会匹配 `<div aria-disabled="true">`，provider 也不会替你实现这些交互。能使用原生按钮时不要用 `<div>` 模拟。
+
+## 10. 版本升级与发布
+
+以下命令在 `packages/ui` 目录执行，默认发布 patch 版本：
+
+```sh
+npm run release
+npm run release:patch
+npm run release:minor
+npm run release:major
+```
+
+发布前必须先完成 `npm login`，并确认当前账号有权发布 `@svp-chain-sdk/ui`。命令按顺序执行：
+
+1. `npm run build`、`npm run typecheck`、`npm run test`；任一失败都会立即停止，版本不会被修改，也不会发布。
+2. 通过后使用 `npm version <type> --no-git-tag-version` 更新 `package.json`，不创建 Git commit/tag。
+3. 使用 `pnpm install --lockfile-only --ignore-scripts` 同步仓库的 `pnpm-lock.yaml`，再执行 `npm publish --access public`。
+
+首次发布或正式发布前，建议先运行完整的安全演练：
+
+```sh
+npm run release -- --dry-run
+npm run release:minor -- --dry-run
+```
+
+`--dry-run` 仍会运行 build、typecheck、test，并执行 npm 的发布包校验，但不会升级版本、写入锁文件或上传 registry。它不会验证 npm 登录权限或版本是否已被占用。正式发布前请确认 package version 尚未存在于 npm；失败时脚本会输出失败步骤和退出码，不输出 npm 配置或凭据。版本升级成功后，若锁文件同步或 npm 发布失败，版本文件可能已改变，需要人工检查后再重试；脚本不会自动回滚或覆盖工作区改动。
+
+`prepublishOnly` 保留为 npm 的独立发布保护，会再次运行质量检查；`release` 脚本不依赖 Git 提交或 tag。
+
+## 11. 当前公开入口速查
+
+以 `packages/ui/package.json` 当前的 `exports` 为准：
+
+| 导入路径 | 当前内容 |
+| --- | --- |
+| `@svp-chain-sdk/ui/tailwind` | 默认 Tailwind plugin；具名 `uiButtonComponents`、`uiComponents` |
+| `@svp-chain-sdk/ui` | 可选 React `Button`、`buttonVariants`、`ButtonProps` 和 `cn` |
+| `@svp-chain-sdk/ui/styles.css` | 包构建产出的 Tailwind v4 CSS 样式入口；当前不包含 provider 的 `.ui-button*` 规则 |
+
+所有 JavaScript 入口均按 ESM 使用。公开 API 之外的源码路径不属于 package exports，不应从消费项目直接导入。

package/dist/button.d.ts

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import { type VariantProps } from 'class-variance-authority';
+export declare const buttonVariants: (props?: ({
+    variant?: "default" | "secondary" | "outline" | "ghost" | "destructive" | null | undefined;
+    size?: "sm" | "md" | "lg" | "icon" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+type ButtonBaseProps = VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+};
+export type ButtonProps = ButtonBaseProps & React.HTMLAttributes<HTMLElement> & {
+    type?: React.ButtonHTMLAttributes<HTMLButtonElement>['type'];
+};
+/** With `asChild`, the ref targets the slotted child, which may not be a button. */
+export declare const Button: React.ForwardRefExoticComponent<VariantProps<(props?: ({
+    variant?: "default" | "secondary" | "outline" | "ghost" | "destructive" | null | undefined;
+    size?: "sm" | "md" | "lg" | "icon" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string> & {
+    asChild?: boolean;
+} & React.HTMLAttributes<HTMLElement> & {
+    type?: React.ButtonHTMLAttributes<HTMLButtonElement>["type"];
+} & React.RefAttributes<HTMLElement>>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Button, buttonVariants } from './button';
+export type { ButtonProps } from './button';
+export { cn } from './utils';