@fredwsw/frontend-rules 1.0.0

package/README.md

@@ -0,0 +1,302 @@
+# `@sanshui/frontend-rules` 使用说明
+
+本文档说明如何把当前仓库的规则模板打包成一个可执行 npm 包，并通过 `pnpm dlx` 在其他项目一键同步到项目根目录。
+
+## 目标
+
+- 发布一个包：`@sanshui/frontend-rules`
+- 在任意项目根目录执行：
+
+```bash
+pnpm dlx @sanshui/frontend-rules@latest
+```
+
+- 自动将包内模板按需同步到当前项目根目录：
+  - 规则和技能同步到 `.cursor`
+  - 组件库文档同步到 `docs`
+
+---
+
+## 一、建议的包结构
+
+新建一个用于发布的仓库（或就在当前仓库整理），结构建议如下：
+
+```text
+frontend-rules/
+  bin/
+    cli.js
+  template/
+    rules/
+      common.mdc
+      uv-ui-docs.mdc
+      ...
+    docs/
+      uv-ui-docs/
+      ...
+    skills/
+      ...
+  package.json
+  README.md
+```
+
+说明：
+
+- `template/rules`：规则文件模板。
+- `template/docs`：组件库文档模板，按用户选择复制。
+- `template/skills`：技能模板。
+- `bin/cli.js`：`pnpm dlx` 实际执行入口。
+
+---
+
+## 二、`package.json` 示例
+
+> 包名改成你的正式名：`@sanshui/frontend-rules`
+
+```json
+{
+  "name": "@sanshui/frontend-rules",
+  "version": "1.0.0",
+  "description": "Sync latest .cursor rules into project root",
+  "type": "module",
+  "bin": {
+    "frontend-rules": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "template",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.8.4",
+    "fs-extra": "^11.2.0"
+  },
+  "license": "MIT"
+}
+```
+
+---
+
+## 三、`bin/cli.js` 示例
+
+> 作用：基础规则与技能始终复制到 `.cursor`，组件库文档支持交互多选后按需复制到项目根目录 `docs`。支持 `--dry-run`。
+
+```js
+#!/usr/bin/env node
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import fs from "fs-extra";
+import { checkbox } from "@inquirer/prompts";
+
+const cwd = process.cwd();
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const root = path.resolve(__dirname, "..");
+const sourceDir = path.join(root, "template");
+const cursorTargetDir = path.join(cwd, ".cursor");
+const docsTargetRootDir = path.join(cwd, "docs");
+const args = new Set(process.argv.slice(2));
+const dryRun = args.has("--dry-run");
+const allLibs = args.has("--all-libs");
+const libsArg = [...args].find((arg) => arg.startsWith("--libs="));
+
+function parseLibsArg() {
+  if (!libsArg) {
+    return null;
+  }
+  const value = libsArg.slice("--libs=".length).trim();
+  if (!value) {
+    return [];
+  }
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+
+async function getLibraryOptions() {
+  const docsRoot = path.join(sourceDir, "docs");
+  const exists = await fs.pathExists(docsRoot);
+  if (!exists) {
+    return [];
+  }
+  const entries = await fs.readdir(docsRoot, { withFileTypes: true });
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => {
+    const docsDirName = entry.name;
+    return {
+      key: docsDirName.replace(/-docs$/i, ""),
+      docsDirName,
+      docsSourcePath: path.join(docsRoot, docsDirName),
+      ruleFileName: `${docsDirName}.mdc`,
+      ruleSourcePath: path.join(sourceDir, "rules", `${docsDirName}.mdc`),
+    };
+  });
+}
+
+async function promptLibraries(options) {
+  if (options.length === 0) {
+    return [];
+  }
+  if (!process.stdin.isTTY) {
+    return options;
+  }
+  const selectedKeys = await checkbox({
+    message: "请选择组件库（方向键移动，空格勾选，回车确认）",
+    choices: options.map((option) => ({ name: option.key, value: option.key })),
+  });
+  if (!selectedKeys || selectedKeys.length === 0) {
+    return [];
+  }
+  return options.filter((option) => new Set(selectedKeys).has(option.key));
+}
+
+async function resolveSelectedLibraries(options) {
+  if (allLibs) {
+    return options;
+  }
+  const parsedLibKeys = parseLibsArg();
+  if (parsedLibKeys !== null) {
+    return options.filter((option) => new Set(parsedLibKeys).has(option.key));
+  }
+  return promptLibraries(options);
+}
+
+async function copyWithDryRun(from, to) {
+  if (dryRun) {
+    console.log("[frontend-rules] copy:", from, "->", to);
+    return;
+  }
+  await fs.copy(from, to, { overwrite: true, recursive: true });
+}
+
+async function main() {
+  await fs.ensureDir(cursorTargetDir);
+  await fs.ensureDir(docsTargetRootDir);
+
+  await copyWithDryRun(path.join(sourceDir, "rules", "common.mdc"), path.join(cursorTargetDir, "rules", "common.mdc"));
+  await copyWithDryRun(path.join(sourceDir, "skills"), path.join(cursorTargetDir, "skills"));
+
+  const options = await getLibraryOptions();
+  const selectedLibraries = await resolveSelectedLibraries(options);
+  for (const library of selectedLibraries) {
+    await copyWithDryRun(library.docsSourcePath, path.join(docsTargetRootDir, library.docsDirName));
+    if (await fs.pathExists(library.ruleSourcePath)) {
+      await copyWithDryRun(library.ruleSourcePath, path.join(cursorTargetDir, "rules", library.ruleFileName));
+    }
+  }
+}
+
+main();
+```
+
+---
+
+## 四、本地联调
+
+在包仓库目录执行：
+
+```bash
+pnpm install
+node ./bin/cli.js --dry-run
+node ./bin/cli.js
+```
+
+然后检查当前目录是否生成/更新了：
+
+- `.cursor/rules`
+- `.cursor/skills`
+- `docs/<组件库>-docs`
+
+---
+
+## 五、发布到 npm
+
+1. 登录 npm（首次）
+
+```bash
+npm login
+```
+
+2. 发布（Scoped 包通常建议公开）
+
+```bash
+npm publish --access public
+```
+
+3. 后续更新流程
+
+```bash
+# 修改 template/.cursor 内容后
+npm version patch
+npm publish --access public
+```
+
+---
+
+## 六、在其他项目中使用
+
+进入目标项目根目录，执行：
+
+```bash
+pnpm dlx @sanshui/frontend-rules@latest
+```
+
+常用变体：
+
+```bash
+# 只预览，不落盘（若你实现了 --dry-run 参数）
+pnpm dlx @sanshui/frontend-rules@latest --dry-run
+
+# 不交互，直接选择全部组件库
+pnpm dlx @sanshui/frontend-rules@latest --all-libs
+
+# 不交互，指定组件库（可多选，逗号分隔）
+pnpm dlx @sanshui/frontend-rules@latest --libs=uv-ui,first-ui
+```
+
+---
+
+## 七、推荐约定（团队协作）
+
+- 把 `.cursor` 规则维护统一放在 `@sanshui/frontend-rules`，业务仓库不各自散改。
+- 每次规则更新都发版，业务仓库按需执行 `pnpm dlx ...@latest` 同步。
+- 若业务仓库存在少量本地特化，可约定放在单独文件并在同步后手动合并。
+
+---
+
+## 八、常见问题
+
+### 1）`pnpm dlx` 没拿到最新版本？
+
+- 显式指定 `@latest`：
+
+```bash
+pnpm dlx @sanshui/frontend-rules@latest
+```
+
+- 确认刚发布版本已在 npm 可见。
+
+### 2）会不会覆盖本地 `.cursor`？
+
+- 当前示例是覆盖策略（`overwrite: true`）。
+- 如果你想保守一点，可扩展参数：
+  - `--force` 才覆盖
+  - 默认仅拷贝不存在文件
+  - 或执行前先备份到 `.cursor.bak-时间戳`
+
+### 3）如何控制复制哪些组件库文档？
+
+- 交互模式下支持方向键上下移动、空格勾选、回车确认（基于 `@inquirer/prompts`）。
+- 非交互可用 `--libs=uv-ui,first-ui`。
+- 全量组件库可用 `--all-libs`。
+
+---
+
+## 九、最小执行清单
+
+1. 准备 `template/rules`、`template/docs`、`template/skills` 模板目录。  
+2. 写好 `bin/cli.js` 复制逻辑。  
+3. 配置 `package.json` 的 `name`、`bin`、`files`。  
+4. `npm publish --access public`。  
+5. 在业务项目运行：`pnpm dlx @sanshui/frontend-rules@latest`，按提示多选组件库。
+

package/bin/cli.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import fs from "fs-extra";
+import { checkbox } from "@inquirer/prompts";
+
+const cwd = process.cwd();
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const root = path.resolve(__dirname, "..");
+const sourceDir = path.join(root, "template");
+const cursorTargetDir = path.join(cwd, ".cursor");
+const docsTargetRootDir = path.join(cwd, "docs");
+const args = new Set(process.argv.slice(2));
+const dryRun = args.has("--dry-run");
+const allLibs = args.has("--all-libs");
+const libsArg = [...args].find((arg) => arg.startsWith("--libs="));
+
+function parseLibsArg() {
+  if (!libsArg) {
+    return null;
+  }
+  const value = libsArg.slice("--libs=".length).trim();
+  if (!value) {
+    return [];
+  }
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+async function getLibraryOptions() {
+  const docsRoot = path.join(sourceDir, "docs");
+  const exists = await fs.pathExists(docsRoot);
+  if (!exists) {
+    return [];
+  }
+
+  const entries = await fs.readdir(docsRoot, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const docsDirName = entry.name;
+      const docsSourcePath = path.join(docsRoot, docsDirName);
+      const ruleFileName = `${docsDirName}.mdc`;
+      const ruleSourcePath = path.join(sourceDir, "rules", ruleFileName);
+      const key = docsDirName.replace(/-docs$/i, "");
+      return {
+        key,
+        docsDirName,
+        docsSourcePath,
+        ruleFileName,
+        ruleSourcePath,
+      };
+    });
+}
+
+async function promptLibraries(options) {
+  if (options.length === 0) {
+    return [];
+  }
+
+  if (!process.stdin.isTTY) {
+    console.log("[frontend-rules] 非交互环境，默认选择全部组件库。可用 --libs=... 精确指定。");
+    return options;
+  }
+
+  const selectedKeys = await checkbox({
+    message: "请选择组件库（方向键移动，空格勾选，回车确认）",
+    choices: options.map((option) => ({
+      name: option.key,
+      value: option.key,
+    })),
+  });
+  if (!selectedKeys || selectedKeys.length === 0) {
+    return [];
+  }
+  const selectedSet = new Set(selectedKeys);
+  return options.filter((option) => selectedSet.has(option.key));
+}
+
+async function resolveSelectedLibraries(options) {
+  if (allLibs) {
+    return options;
+  }
+
+  const parsedLibKeys = parseLibsArg();
+  if (parsedLibKeys !== null) {
+    const keySet = new Set(parsedLibKeys);
+    return options.filter((option) => keySet.has(option.key));
+  }
+
+  return promptLibraries(options);
+}
+
+async function copyWithDryRun(from, to) {
+  if (dryRun) {
+    console.log("[frontend-rules] copy:", from, "->", to);
+    return;
+  }
+  await fs.copy(from, to, { overwrite: true, recursive: true });
+}
+
+async function main() {
+  const exists = await fs.pathExists(sourceDir);
+  if (!exists) {
+    console.error("[frontend-rules] 模板目录不存在:", sourceDir);
+    process.exit(1);
+  }
+
+  if (dryRun) {
+    console.log("[frontend-rules] dry-run 模式，不写入文件");
+  }
+
+  const libraryOptions = await getLibraryOptions();
+  const selectedLibraries = await resolveSelectedLibraries(libraryOptions);
+
+  await fs.ensureDir(cursorTargetDir);
+
+  const commonRuleSource = path.join(sourceDir, "rules", "common.mdc");
+  const commonRuleTarget = path.join(cursorTargetDir, "rules", "common.mdc");
+  const skillsSource = path.join(sourceDir, "skills");
+  const skillsTarget = path.join(cursorTargetDir, "skills");
+
+  await copyWithDryRun(commonRuleSource, commonRuleTarget);
+  await copyWithDryRun(skillsSource, skillsTarget);
+
+  if (selectedLibraries.length > 0) {
+    await fs.ensureDir(docsTargetRootDir);
+  }
+
+  for (const library of selectedLibraries) {
+    const docsTargetPath = path.join(docsTargetRootDir, library.docsDirName);
+    await copyWithDryRun(library.docsSourcePath, docsTargetPath);
+
+    const ruleExists = await fs.pathExists(library.ruleSourcePath);
+    if (ruleExists) {
+      const ruleTargetPath = path.join(cursorTargetDir, "rules", library.ruleFileName);
+      await copyWithDryRun(library.ruleSourcePath, ruleTargetPath);
+    }
+  }
+
+  const selectedKeys = selectedLibraries.map((item) => item.key).join(", ") || "无";
+  console.log("[frontend-rules] 已同步基础规则与技能目录。");
+  console.log("[frontend-rules] 已选择组件库:", selectedKeys);
+  console.log("[frontend-rules] .cursor 目标目录:", cursorTargetDir);
+  console.log("[frontend-rules] docs 目标目录:", docsTargetRootDir);
+}
+
+main().catch((err) => {
+  console.error("[frontend-rules] 执行失败:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@fredwsw/frontend-rules",
+  "version": "1.0.0",
+  "description": "Sync latest .cursor rules into project root",
+  "type": "module",
+  "bin": {
+    "frontend-rules": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "template",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.8.4",
+    "fs-extra": "^11.2.0"
+  },
+  "license": "MIT"
+}

package/template/docs/uv-ui-docs/action-sheet-cn.md

@@ -0,0 +1,180 @@
+---
+group: 反馈
+category: Components
+title: ActionSheet
+subtitle: 操作菜单
+description: 从底部弹出操作菜单供用户选择，功能类似 uni.showActionSheet，提供更灵活的配置与统一的多端表现。
+demo:
+  cols: 2
+---
+
+## 何时使用 {#when-to-use}
+
+`uv-action-sheet` 用于 **从底部弹出一组操作选项** 的场景：
+
+- 替代 `uni.showActionSheet`，统一多端表现
+- 需要带描述、副标题、禁用状态、加载状态、开放能力等更复杂选项配置
+- 与弹窗、操作确认、分享面板等组合使用
+
+> 完整示例下载地址：[uv-ui 插件市场](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+## 平台兼容性 {#platform}
+
+| App（vue） | App（nvue） | H5 | 小程序 | VUE2 | VUE3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | √ | √ | √ | √ | √ |
+
+**组件名：** `uv-action-sheet`
+
+## 代码演示 {#examples}
+
+### 基本使用 {#basic}
+
+通过 `title`、`cancelText`、`description` 配置标题、取消按钮文案、顶部描述；  
+通过 `actions` 配置选项数组，使用 `ref` 调用 `open()` 打开。
+
+```vue
+<template>
+  <view>
+    <uv-action-sheet
+      ref="actionSheet"
+      :actions="list"
+      title="标题"
+      @select="select"
+      @close="close"
+    ></uv-action-sheet>
+
+    <button @click="open">打开ActionSheet</button>
+  </view>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      list: [
+        {
+          name: '选项一',
+          subname: '选项一描述',
+          color: '#ffaa7f',
+          fontSize: '20'
+        },
+        {
+          name: '选项二禁用',
+          disabled: true
+        },
+        {
+          name: '开启load加载',
+          loading: true
+        }
+      ]
+    }
+  },
+  methods: {
+    open() {
+      this.$refs.actionSheet.open()
+    },
+    select(e) {
+      console.log('选中该项：', e)
+    },
+    close() {
+      console.log('关闭')
+    }
+  }
+}
+</script>
+```
+
+### 控制遮罩及点击项关闭行为 {#close-control}
+
+通过 `closeOnClickOverlay` 和 `closeOnClickAction` 分别控制 **点击遮罩**、**点击菜单项** 时是否关闭弹窗。
+
+```vue
+<uv-action-sheet
+  ref="actionSheet"
+  :actions="list"
+  title="标题"
+  :closeOnClickOverlay="false"
+  :closeOnClickAction="false"
+  @select="select"
+  @close="close"
+></uv-action-sheet>
+```
+
+### 选项开放能力（小程序） {#open-type}
+
+结合小程序 `button` 的开放能力使用，例如分享、获取用户信息等。
+
+```vue
+<uv-action-sheet
+  ref="actionSheet"
+  :actions="list"
+  title="开放能力"
+  @select="select"
+  @close="close"
+></uv-action-sheet>
+```
+
+`actions` 中可设置：
+
+- `openType: 'share'`
+- `openType: 'getUserInfo'`
+- `openType: 'contact'`
+
+等。
+
+## API {#api}
+
+### ActionSheet Props {#props}
+
+| 参数 | 说明 | 类型 | 默认值 | 可选值 |
+| --- | --- | --- | --- | --- |
+| title | 标题 | String | - | - |
+| description | 选项上方的描述信息 | String | - | - |
+| actions | 选项配置数组，见下方「Actions Props」 | Array\<Object> | [] | - |
+| cancelText | 取消按钮文字（非空时显示取消按钮） | String | - | - |
+| safeAreaInsetBottom | 是否开启底部安全区适配 | Boolean | false | true \| false |
+| closeOnClickOverlay | 点击遮罩是否允许关闭组件 | Boolean | - | - |
+| closeOnClickAction | 点击某个菜单项时是否关闭组件 | String | true | true \| false |
+| round | 菜单面板圆角值 | String \| Number | 0 | - |
+| lang | 返回用户信息的语言（小程序） | String | en | en \| zh_CN \| zh_TW |
+| sessionFrom | 会话来源（`open-type="contact"` 有效，仅微信小程序） | String | - | - |
+| sendMessageTitle | 会话内消息卡片标题 | String | - | - |
+| sendMessagePath | 会话内消息卡片跳转路径 | String | - | - |
+| sendMessageImg | 会话内消息卡片图片 | String | - | - |
+| showMessageCard | 是否显示会话内消息卡片 | Boolean | false | true \| false |
+| appParameter | 打开 APP 时传递的参数，`openType="launchApp"` 有效 | String | - | - |
+
+### Actions Props {#actions-props}
+
+单个 `actions` 元素支持以下字段：
+
+| 参数 | 说明 | 类型 | 默认值 | 可选值 |
+| --- | --- | --- | --- | --- |
+| openType | 小程序开放能力类型 | String | '' | - |
+| disabled | 是否禁用该菜单 | Boolean | false | true \| false |
+| loading | 是否显示加载状态（开启后文字不显示） | Boolean | false | true \| false |
+| name | 菜单标题 | String | '' | - |
+| subname | 菜单描述 | String | '' | - |
+| fontSize | `name` 字体大小（px/rpx） | String | 16px | - |
+| color | `name` 字体颜色 | String | #303133 | - |
+
+### Methods {#methods}
+
+| 方法名 | 说明 |
+| --- | --- |
+| open | 打开操作菜单 |
+| close | 关闭操作菜单 |
+
+### Events {#events}
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| @select | 点击 ActionSheet 列表项时触发 | 选项对象 |
+| @close | 点击取消按钮时触发；若需点击遮罩触发，需设置 `closeOnClickOverlay="true"` | - |
+| @getuserinfo | 获取用户信息回调，`openType="getUserInfo"` 有效 | detail |
+| @contact | 客服消息回调，`openType="contact"` 有效 | - |
+| @getphonenumber | 获取用户手机号回调，`openType="getPhoneNumber"` 有效 | - |
+| @error | 使用开放能力出错时回调，`openType="error"` 有效 | - |
+| @launchapp | 打开 APP 成功回调，`openType="launchApp"` 有效 | - |
+| @opensetting | 打开授权设置页后回调，`openType="openSetting"` 有效 | - |