{"_id":"@ark-x/prompt","name":"@ark-x/prompt","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@ark-x/prompt","version":"0.0.1","description":"beautiful, ready-to-use CLI prompt components","keywords":[],"license":"MIT","author":{"name":"Derrick","email":"chens.cls@gmail.com"},"main":"./dist/cjs/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","dependencies":{"is-unicode-supported":"^2.1.0","picocolors":"^1.1.1","sisteransi":"^1.0.5","wrap-ansi":"^8.1.0","@ark-x/clack":"^0.0.1"},"devDependencies":{"typescript":"^5.0.0"},"publishConfig":{"access":"public"},"scripts":{"build":"father build","dev":"father dev","typecheck":"tsc --noEmit"},"_id":"@ark-x/prompt@0.0.1","_integrity":"sha512-7/U6hhlV8lXjmdvHsJCOo0G4Bw9UnIbQBuxM4JMcH/epHQmmUk/KlM2Q4IDLNOJV5FpyMmMyXmiB0F9T1gk80A==","_resolved":"/private/var/folders/j8/d46gh41n3sjc04g_v9lxvq680000gn/T/0cd65c4b2e86cb81585cb170291e4928/ark-x-prompt-0.0.1.tgz","_from":"file:ark-x-prompt-0.0.1.tgz","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-7/U6hhlV8lXjmdvHsJCOo0G4Bw9UnIbQBuxM4JMcH/epHQmmUk/KlM2Q4IDLNOJV5FpyMmMyXmiB0F9T1gk80A==","shasum":"f296a9bae418f7f88086cb77f60811fc61c3aeef","tarball":"https://registry.npmjs.org/@ark-x/prompt/-/prompt-0.0.1.tgz","fileCount":99,"unpackedSize":220997,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDeP5g3XzPcDZr9jVka6ZALOmcdo4Uh2j4Dj5wf2bUWZgIgVDv39xIGUUsfMxWx+ERkIeBulfwytkiJ3gdd/Vt3/yc="}]},"_npmUser":{"name":"nu1nux","email":"nu1nux@outlook.com"},"directories":{},"maintainers":[{"name":"nu1nux","email":"nu1nux@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/prompt_0.0.1_1761446007246_0.7966680029361104"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-26T02:33:27.163Z","0.0.1":"2025-10-26T02:33:27.459Z","modified":"2025-10-26T02:33:27.767Z"},"maintainers":[{"name":"nu1nux","email":"nu1nux@outlook.com"}],"description":"beautiful, ready-to-use CLI prompt components","keywords":[],"author":{"name":"Derrick","email":"chens.cls@gmail.com"},"license":"MIT","readme":"# @ark-x/prompt\n\n> 美观且易用的命令行交互提示库\n\n@ark-x/prompt 是一个构建在 [@ark-x/clack](../@ark-x/clack) 之上的高级命令行交互库，提供开箱即用的样式化提示函数。它专注于提供一致、美观的用户体验，无需复杂配置即可创建专业的 CLI 应用。\n\n## 特性\n\n- 🎨 **美观设计** - 统一的视觉风格和颜色主题\n- 📦 **开箱即用** - 无需配置即可使用\n- 🔧 **完整功能** - 涵盖所有常用的 CLI 交互场景\n- 🎯 **类型安全** - 完整的 TypeScript 类型支持\n- 🚀 **轻量高效** - 最小化依赖，性能优异\n- ♿ **优雅降级** - 自动适配终端环境\n\n## 安装\n\n```bash\npnpm add @ark-x/prompt\n```\n\n## 快速开始\n\n```typescript\nimport { intro, outro, text, confirm, select } from \"@ark-x/prompt\";\n\nasync function main() {\n  intro(\"欢迎使用我的 CLI 工具\");\n\n  const name = await text({\n    message: \"请输入您的名字\",\n    placeholder: \"John Doe\",\n  });\n\n  const shouldContinue = await confirm({\n    message: \"是否继续？\",\n  });\n\n  if (shouldContinue) {\n    const color = await select({\n      message: \"选择您喜欢的颜色\",\n      options: [\n        { value: \"red\", label: \"红色\" },\n        { value: \"green\", label: \"绿色\" },\n        { value: \"blue\", label: \"蓝色\" },\n      ],\n    });\n\n    outro(`您选择了 ${color}，感谢使用！`);\n  }\n}\n\nmain();\n```\n\n## API 文档\n\n### 提示函数\n\n#### text\n\n文本输入提示，用于收集用户的单行文本输入。\n\n```typescript\nimport { text } from \"@ark-x/prompt\";\n\nconst name = await text({\n  message: \"请输入您的名字\",\n  placeholder: \"John Doe\",\n  initialValue: \"\",\n  defaultValue: \"Guest\",\n  validate: (value) => {\n    if (!value) return \"名字不能为空\";\n  },\n});\n```\n\n**选项：**\n\n- `message` (string, 必需) - 提示消息\n- `placeholder` (string) - 占位符文本\n- `initialValue` (string) - 初始值\n- `defaultValue` (string) - 默认值\n- `validate` (function) - 验证函数，返回错误消息或 void\n\n#### password\n\n密码输入提示，输入内容会被掩码字符替换。\n\n```typescript\nimport { password } from \"@ark-x/prompt\";\n\nconst pwd = await password({\n  message: \"请输入密码\",\n  validate: (value) => {\n    if (value.length < 6) return \"密码至少需要 6 个字符\";\n  },\n});\n```\n\n**选项：**\n\n- `message` (string, 必需) - 提示消息\n- `validate` (function) - 验证函数\n\n#### confirm\n\n确认提示，用于获取用户的是/否选择。\n\n```typescript\nimport { confirm } from \"@ark-x/prompt\";\n\nconst shouldContinue = await confirm({\n  message: \"是否继续？\",\n  active: \"是\",\n  inactive: \"否\",\n  initialValue: true,\n});\n```\n\n**选项：**\n\n- `message` (string, 必需) - 提示消息\n- `active` (string) - 激活选项文本，默认 \"Yes\"\n- `inactive` (string) - 未激活选项文本，默认 \"No\"\n- `initialValue` (boolean) - 初始值，默认 true\n\n#### select\n\n单选提示，从列表中选择一个选项。\n\n```typescript\nimport { select } from \"@ark-x/prompt\";\n\nconst framework = await select({\n  message: \"选择一个框架\",\n  options: [\n    { value: \"react\", label: \"React\", hint: \"推荐\" },\n    { value: \"vue\", label: \"Vue\" },\n    { value: \"angular\", label: \"Angular\" },\n  ],\n  initialValue: \"react\",\n  maxItems: 5,\n});\n```\n\n**选项：**\n\n- `message` (string, 必需) - 提示消息\n- `options` (array, 必需) - 选项数组，每项包含 `value`、`label`（可选）、`hint`（可选）\n- `initialValue` (any) - 初始选中的值\n- `maxItems` (number) - 最多显示的项数\n\n#### selectKey\n\n键选择提示，通过按键快速选择选项。\n\n```typescript\nimport { selectKey } from \"@ark-x/prompt\";\n\nconst action = await selectKey({\n  message: \"请选择操作\",\n  options: [\n    { value: \"y\", label: \"确认\" },\n    { value: \"n\", label: \"取消\" },\n    { value: \"a\", label: \"全部\" },\n  ],\n});\n```\n\n**选项：**\n\n- `message` (string, 必需) - 提示消息\n- `options` (array, 必需) - 选项数组\n\n#### multiselect\n\n多选提示，从列表中选择多个选项。\n\n```typescript\nimport { multiselect } from \"@ark-x/prompt\";\n\nconst features = await multiselect({\n  message: \"选择需要的功能\",\n  options: [\n    { value: \"typescript\", label: \"TypeScript\", hint: \"推荐\" },\n    { value: \"eslint\", label: \"ESLint\" },\n    { value: \"prettier\", label: \"Prettier\" },\n  ],\n  initialValues: [\"typescript\"],\n  required: true,\n  maxItems: 10,\n});\n```\n\n**选项：**\n\n- `message` (string, 必需) - 提示消息\n- `options` (array, 必需) - 选项数组\n- `initialValues` (array) - 初始选中的值数组\n- `required` (boolean) - 是否至少选择一项，默认 true\n- `maxItems` (number) - 最多显示的项数\n- `cursorAt` (any) - 初始光标位置\n\n#### groupMultiselect\n\n分组多选提示，支持选项分组的多选。\n\n```typescript\nimport { groupMultiselect } from \"@ark-x/prompt\";\n\nconst packages = await groupMultiselect({\n  message: \"选择要安装的包\",\n  options: {\n    前端框架: [\n      { value: \"react\", label: \"React\" },\n      { value: \"vue\", label: \"Vue\" },\n    ],\n    构建工具: [\n      { value: \"vite\", label: \"Vite\" },\n      { value: \"webpack\", label: \"Webpack\" },\n    ],\n  },\n  required: false,\n});\n```\n\n**选项：**\n\n- `message` (string, 必需) - 提示消息\n- `options` (object, 必需) - 分组选项对象\n- `initialValues` (array) - 初始选中的值数组\n- `required` (boolean) - 是否至少选择一项，默认 true\n- `cursorAt` (any) - 初始光标位置\n\n### 输出函数\n\n#### intro\n\n显示 CLI 应用的开始标题。\n\n```typescript\nimport { intro } from \"@ark-x/prompt\";\n\nintro(\"欢迎使用我的 CLI 工具\");\n```\n\n#### outro\n\n显示 CLI 应用的结束消息。\n\n```typescript\nimport { outro } from \"@ark-x/prompt\";\n\noutro(\"感谢使用！\");\n```\n\n#### log\n\n输出日志消息，支持多种类型。\n\n```typescript\nimport { log } from \"@ark-x/prompt\";\n\nlog.info(\"这是一条信息\");\nlog.success(\"操作成功！\");\nlog.warning(\"这是一个警告\");\nlog.error(\"发生错误！\");\nlog.step(\"执行步骤 1\");\nlog.message(\"普通消息\");\n```\n\n**方法：**\n\n- `log.info(message)` - 信息消息\n- `log.success(message)` - 成功消息\n- `log.warning(message)` - 警告消息\n- `log.error(message)` - 错误消息\n- `log.step(message)` - 步骤消息\n- `log.message(message, options)` - 自定义消息\n\n#### note\n\n显示带标题的多行消息框。\n\n```typescript\nimport { note } from \"@ark-x/prompt\";\n\nnote(\"这是消息内容\\n可以多行显示\", \"标题\");\n```\n\n#### box\n\n显示一个装饰性的消息框。\n\n```typescript\nimport { box } from \"@ark-x/prompt\";\n\nbox(\"欢迎使用 @ark-x/prompt！\");\n```\n\n#### cancel\n\n显示取消消息并退出进程。\n\n```typescript\nimport { cancel } from \"@ark-x/prompt\";\n\ncancel(\"操作已取消\");\n```\n\n#### taskLog\n\n显示任务状态日志。\n\n```typescript\nimport { taskLog } from \"@ark-x/prompt\";\n\ntaskLog({\n  message: \"构建项目\",\n  status: \"active\", // 'active' | 'error' | 'success' | 'cancel'\n});\n```\n\n### 进度指示器\n\n#### spinner\n\n创建一个加载动画。\n\n```typescript\nimport { spinner } from \"@ark-x/prompt\";\n\nconst s = spinner();\ns.start(\"正在加载...\");\n\n// 执行异步操作\nawait someAsyncTask();\n\ns.stop(\"加载完成\");\n```\n\n**方法：**\n\n- `spinner.start(message?)` - 开始显示加载动画\n- `spinner.stop(message?, code?)` - 停止加载动画（code: 0=成功, 1=取消, 2=错误）\n- `spinner.message(message)` - 更新加载消息\n\n#### tasks\n\n执行一组任务，每个任务都有自己的 spinner。\n\n```typescript\nimport { tasks } from \"@ark-x/prompt\";\n\nawait tasks([\n  {\n    title: \"安装依赖\",\n    task: async (message) => {\n      await installDependencies();\n      message(\"依赖安装完成\");\n    },\n  },\n  {\n    title: \"构建项目\",\n    task: async () => {\n      await build();\n      return \"构建成功\";\n    },\n    enabled: true,\n  },\n]);\n```\n\n**任务选项：**\n\n- `title` (string, 必需) - 任务标题\n- `task` (function, 必需) - 任务函数，可以返回消息或使用 message 回调\n- `enabled` (boolean) - 是否启用该任务，默认 true\n\n### 提示组\n\n#### group\n\n将多个提示组合成一个组，按顺序执行并返回所有结果。\n\n```typescript\nimport { group, text, confirm, select } from \"@ark-x/prompt\";\n\nconst results = await group(\n  {\n    name: () => text({ message: \"请输入名字\" }),\n\n    age: () =>\n      text({\n        message: \"请输入年龄\",\n        validate: (value) => {\n          if (isNaN(Number(value))) return \"年龄必须是数字\";\n        },\n      }),\n\n    // 可以访问之前的结果\n    shouldContinue: ({ results }) =>\n      confirm({\n        message: `${results.name}，是否继续？`,\n      }),\n\n    color: ({ results }) => {\n      if (!results.shouldContinue) return;\n      return select({\n        message: \"选择颜色\",\n        options: [\n          { value: \"red\", label: \"红色\" },\n          { value: \"blue\", label: \"蓝色\" },\n        ],\n      });\n    },\n  },\n  {\n    onCancel: ({ results }) => {\n      cancel(\"操作已取消\");\n    },\n  }\n);\n\nconsole.log(results); // { name: 'John', age: '25', shouldContinue: true, color: 'red' }\n```\n\n**选项：**\n\n- `onCancel` (function) - 当某个提示被取消时的回调函数\n\n### 工具函数\n\n#### isCancel\n\n检查用户是否取消了提示（按 Ctrl+C）。\n\n```typescript\nimport { text, isCancel } from \"@ark-x/prompt\";\n\nconst name = await text({ message: \"请输入名字\" });\n\nif (isCancel(name)) {\n  console.log(\"用户取消了操作\");\n  process.exit(0);\n}\n```\n\n## 键盘快捷键\n\n所有提示都支持以下键盘操作：\n\n- `↑/k` - 向上移动\n- `↓/j` - 向下移动\n- `←/h` - 向左移动（确认提示）\n- `→/l` - 向右移动（确认提示）\n- `Space` - 切换选中状态（多选）\n- `Enter` - 确认提交\n- `Ctrl+C` - 取消操作\n\n## 完整示例\n\n### 基础 CLI 工具\n\n```typescript\nimport {\n  intro,\n  outro,\n  text,\n  select,\n  multiselect,\n  confirm,\n  spinner,\n  isCancel,\n  cancel,\n} from \"@ark-x/prompt\";\n\nasync function main() {\n  console.clear();\n\n  intro(\"创建新项目\");\n\n  const project = await group(\n    {\n      name: () =>\n        text({\n          message: \"项目名称\",\n          placeholder: \"my-app\",\n          validate: (value) => {\n            if (!value) return \"项目名称不能为空\";\n          },\n        }),\n\n      type: () =>\n        select({\n          message: \"项目类型\",\n          options: [\n            { value: \"web\", label: \"Web 应用\" },\n            { value: \"cli\", label: \"CLI 工具\" },\n            { value: \"lib\", label: \"库\" },\n          ],\n        }),\n\n      features: () =>\n        multiselect({\n          message: \"选择功能\",\n          options: [\n            { value: \"typescript\", label: \"TypeScript\", hint: \"推荐\" },\n            { value: \"eslint\", label: \"ESLint\" },\n            { value: \"prettier\", label: \"Prettier\" },\n            { value: \"test\", label: \"测试框架\" },\n          ],\n          required: false,\n        }),\n\n      install: () =>\n        confirm({\n          message: \"是否立即安装依赖？\",\n        }),\n    },\n    {\n      onCancel: () => {\n        cancel(\"项目创建已取消\");\n        process.exit(0);\n      },\n    }\n  );\n\n  const s = spinner();\n  s.start(\"正在创建项目...\");\n\n  // 模拟项目创建\n  await new Promise((resolve) => setTimeout(resolve, 2000));\n\n  s.stop(\"项目创建完成！\");\n\n  outro(`成功创建项目 ${project.name}！`);\n}\n\nmain().catch(console.error);\n```\n\n### 使用 tasks 执行多个任务\n\n```typescript\nimport { intro, outro, tasks } from \"@ark-x/prompt\";\n\nasync function build() {\n  intro(\"开始构建\");\n\n  await tasks([\n    {\n      title: \"清理构建目录\",\n      task: async () => {\n        await cleanDist();\n      },\n    },\n    {\n      title: \"编译 TypeScript\",\n      task: async (message) => {\n        await compileTS();\n        message(\"TypeScript 编译完成\");\n      },\n    },\n    {\n      title: \"打包资源\",\n      task: async () => {\n        await bundleAssets();\n        return \"资源打包完成\";\n      },\n    },\n  ]);\n\n  outro(\"构建完成！\");\n}\n\nbuild();\n```\n\n## 与 @ark-x/clack 的关系\n\n- **@ark-x/clack**：提供底层提示原语和基础类，适合构建自定义提示组件\n- **@ark-x/prompt**：构建在 @ark-x/clack 之上，提供样式化的高级提示函数，开箱即用\n\n如果您需要自定义提示组件的渲染逻辑和行为，可以使用 [@ark-x/clack](../@ark-x/clack)。\n\n## 依赖项\n\n- `@ark-x/clack` - 核心提示引擎\n- `picocolors` - 终端颜色\n- `sisteransi` - ANSI 转义序列\n- `wrap-ansi` - 文本换行\n- `is-unicode-supported` - Unicode 支持检测\n\n## 许可证\n\nMIT\n\n## 作者\n\nDerrick <chens.cls@gmail.com>\n","readmeFilename":"README.md","_rev":"1-5230ce349b6c2b6eeedf076797090219"}