inquirer-form 0.2.0 → 0.3.0

package/LICENSE

@@ -1,22 +1,22 @@
-MIT License
-
-Copyright (c) 2025 ag-form Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
+MIT License
+
+Copyright (c) 2025 ag-form Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -1,44 +1,108 @@
 # inquirer-form
 
-`inquirer-form` 是一套面向 [Inquirer.js](https://github.com/SBoudrias/Inquirer.js/) 的可视化表单设计/运行组件，构建在 `agilebuilder-form` 之上，帮助团队快速把「拖拽式 Schema」同步成 Inquirer `QuestionCollection` 并在 Web 端模拟 prompt 交互。
+English | [简体中文](./README.zh-CN.md)
 
-## 功能亮点
+A Vue 3-based visual form designer and runtime library specifically built for [Inquirer.js](https://github.com/SBoudrias/Inquirer.js/), enabling seamless unification between Web forms and CLI interactions.
 
-- 🧱 Inquirer 专属控件集（input、password、list、checkbox、editor…），可与自定义控件混用
-- 🛠️ `<InquirerFormDesigner>` 拖拽式设计器，内置 Schema 引擎与快照
-- 🧪 `<InquirerFormRuntime>` Web 运行态，实时渲染与数据回写
-- 🔁 `schemaToInquirer` 等工具方法，一键生成 QuestionCollection
-- 🧑‍💻 `<InquirerFormPlayground>` Playground 组件，便于演示与交互测试
+##  Features
 
-## 环境要求
+-  **Visual Designer** - Drag-and-drop form design with WYSIWYG experience
+-  **Multi-Platform Unity** - One schema drives both Web forms and CLI interactions
+-  **Ready to Use** - 9 built-in Inquirer-specific controls
+-  **Type Safe** - Complete TypeScript type definitions
+-  **i18n Support** - Built-in Chinese and English support
+-  **Flexible Extension** - Support for custom controls and themes
+-  **Lightweight** - Built on agilebuilder-form
 
-- Node.js ≥ `20.19.0`（或 ≥ `22.12.0`）
-- 包管理器：`npm`（亦可兼容 `pnpm`、`yarn`，命令需自适应）
-- 需要在宿主应用中安装的 peerDependencies：
-  - `vue@^3.5`
-  - `element-plus@^2.11`
-  - `vuedraggable@^4.1`
-
-## 安装
+##  Installation
 
 ```bash
 npm install inquirer-form
+```
+
+### Required Dependencies
+
+This package requires `agilebuilder-form` as a core dependency:
+
+```bash
+npm install agilebuilder-form
+```
+
+> **Note**: `vue-i18n` is bundled within this package, so you don't need to install it separately.
 
-# 如同级有 agilebuilder-form，可直接引用本地版本
-npm install agilebuilder-form@file:../ag_form
+### Peer Dependencies
+
+Make sure to install the following peer dependencies:
+
+```bash
+npm install vue@^3.5.0 element-plus@^2.11.7 vuedraggable@^4.1.0
 ```
 
-> 仓库默认把 `agilebuilder-form` 指向 `file:../ag_form`，便于与主库联调；发布到 npm 时无需额外处理。
+### Import Styles
+
+Don't forget to import the required CSS files in your application:
+
+```typescript
+// Import inquirer-form styles
+import 'inquirer-form/style.css'
+
+// Import agilebuilder-form styles
+import 'agilebuilder-form/dist/style.css'
+
+// Import Element Plus styles
+import 'element-plus/dist/index.css'
+```
 
-## 快速开始
+##  Use Cases
 
-```ts
+### CLI Tool Development
+- Configuration wizards for project scaffolding
+- Parameter collection for command-line tools
+- Confirmation flows for batch operations
+
+### Web Application Forms
+- Configuration forms for admin dashboards
+- User registration and settings pages
+- Data entry and editing interfaces
+
+### Multi-Platform Scenarios
+- DevOps tools (CLI operations + Web management)
+- Configuration management systems (CLI config + Web visualization)
+- Automation scripts (CLI execution + Web monitoring)
+
+##  Quick Start
+
+### 1. Install Plugin (Optional)
+
+If you're using the default export, i18n will be automatically installed:
+
+```typescript
+import InquirerForm from 'inquirer-form'
+import { createApp } from 'vue'
+
+const app = createApp(App)
+app.use(InquirerForm) // Automatically installs i18n and registers components
+```
+
+Or register controls manually:
+
+```typescript
 import { registerInquirerControls } from 'inquirer-form'
 
+// Register all Inquirer controls
 registerInquirerControls()
 ```
 
-### 设计器
+### 2. Import Styles
+
+```typescript
+// main.ts or App.vue
+import 'inquirer-form/style.css'
+import 'agilebuilder-form/dist/style.css'
+import 'element-plus/dist/index.css'
+```
+
+### 3. Use the Designer
 
 ```vue
 <script setup lang="ts">
@@ -46,7 +110,9 @@ import { InquirerFormDesigner, createInquirerSampleControls } from 'inquirer-for
 import { SchemaEngine } from 'agilebuilder-form'
 
 const engine = new SchemaEngine()
-engine.getSchema().controls = createInquirerSampleControls()
+
+// Optional: Load sample form
+engine.getSchema().controls = createInquirerSampleControls((key) => key)
 </script>
 
 <template>
@@ -54,7 +120,7 @@ engine.getSchema().controls = createInquirerSampleControls()
 </template>
 ```
 
-### 运行态
+### 4. Web Runtime
 
 ```vue
 <script setup lang="ts">
@@ -63,7 +129,11 @@ import { InquirerFormRuntime } from 'inquirer-form'
 import type { FormData, FormSchema } from 'agilebuilder-form'
 
 const formData = ref<FormData>({})
-const schema: FormSchema = {/* 从设计器或接口获取 */}
+const schema: FormSchema = {
+  controls: [
+    // Get from designer or define manually
+  ]
+}
 </script>
 
 <template>
@@ -71,70 +141,333 @@ const schema: FormSchema = {/* 从设计器或接口获取 */}
 </template>
 ```
 
-### Schema → Inquirer
+### 5. Convert to Inquirer
 
-```ts
+```typescript
 import inquirer from 'inquirer'
 import { schemaToInquirer } from 'inquirer-form'
+import type { FormSchema } from 'agilebuilder-form'
 
+const schema: FormSchema = {
+  // Get from designer or API
+}
+
+// Convert to Inquirer questions
 const questions = schemaToInquirer(schema)
+
+// Use in CLI
 const answers = await inquirer.prompt(questions)
+console.log(answers)
 ```
 
-### Playground
+### 6. Try the Playground
 
 ```bash
+git clone <repository-url>
+cd inquirer-form
 npm install
 npm run dev
 ```
 
-在浏览器中即可体验集成了 Designer / Runtime / JSON 导出的 `<InquirerFormPlayground>`。
-
-## 脚本
-
-| 命令                | 说明                                      |
-| ------------------- | ----------------------------------------- |
-| `npm run dev`       | Vite + Playground 热更新                  |
-| `npm run build`     | 生成 `dist` 产物（ESM + CSS + d.ts）      |
-| `npm run test:unit` | Vitest 单元测试                          |
-| `npm run docs:*`    | VitePress 文档站（可选）                  |
-
-## 发布 npm 模块
-
-1. **准备环境**  
-   确保已登录正确的 npm 账号，并使用 Node.js 满足 `engines` 要求。使用 `npm ci` 或 `npm install` 保证依赖一致。
-2. **构建产物**  
-   ```bash
-   npm run build
-   ```
-   该命令会输出 `dist/` 目录（包含 `inquirer-form.es.js`、`inquirer-form.umd.js`、`inquirer-form.css`、`index.d.ts`），并通过 `vite-plugin-dts` 生成类型声明。
-3. **核对发布内容**  
-   `package.json` 的 `"files": ["dist", "README.md", "LICENSE"]` 会确保只发布：
-   - `dist/`：打包后的 JS/CSS/类型文件
-   - `README.md`：使用文档
-   - `LICENSE`
-   如需附带额外文件（例如示例或类型增强），可在 `files` 数组中补充路径。
-4. **版本与发布**  
-   ```bash
-   npm version patch   # 或 minor / major
-   npm publish --access public
-   ```
-   若你在 Monorepo/CI 中发布，可使用 `npm publish --provenance` 等附加参数。
-5. **验证**  
-   在空目录下执行 `npm pack` 或 `npm install inquirer-form@<version>`，确认产物与类型均正常。
-
-> ⚠️ 不要把 `docs/`、`src/`、Playground 配置等开发文件放入 npm 包中；`files` 字段已默认排除它们。
-
-## 与 agilebuilder-form 联调
-
-当 `agilebuilder-form` 与本项目位于同级目录时，可继续保持 `file:../ag_form` 依赖。若要从 npm 使用正式版本，只需把依赖切换为对应版本号即可。
-
-```json
-"dependencies": {
-  "agilebuilder-form": "^x.y.z"
+Visit the browser to see the complete demo with designer, Web preview, and Inquirer export.
+
+##  API Documentation
+
+### Components
+
+#### InquirerFormDesigner
+
+Visual form designer component.
+
+**Props:**
+- `engine?: SchemaEngine` - Schema engine instance (optional, creates new instance by default)
+- `seedSample?: boolean` - Whether to load sample form (default `false`)
+- `autoRegisterControls?: boolean` - Whether to auto-register controls (default `true`)
+
+**Example:**
+```vue
+<InquirerFormDesigner 
+  :engine="engine" 
+  :seedSample="true"
+  :autoRegisterControls="true"
+/>
+```
+
+#### InquirerFormRuntime
+
+Web form runtime component.
+
+**Props:**
+- `schema: FormSchema` - Form schema (required)
+- `modelValue: FormData` - Form data (v-model)
+
+**Events:**
+- `update:modelValue` - Form data update event
+
+**Example:**
+```vue
+<InquirerFormRuntime v-model="formData" :schema="schema" />
+```
+
+#### InquirerFormPlayground
+
+Complete playground component with designer, runtime, and export features.
+
+**Example:**
+```vue
+<InquirerFormPlayground />
+```
+
+### Functions
+
+#### registerInquirerControls()
+
+Register all built-in Inquirer controls to the global registry.
+
+```typescript
+import { registerInquirerControls } from 'inquirer-form'
+
+registerInquirerControls()
+```
+
+#### schemaToInquirer(schema, options?)
+
+Convert form schema to Inquirer questions.
+
+**Parameters:**
+- `schema: FormSchema` - Form schema
+- `options?: TransformOptions` - Transform options
+  - `includeDisabled?: boolean` - Whether to include disabled fields (default `false`)
+
+**Returns:**
+- `InquirerQuestion[]` - Array of Inquirer questions
+
+**Example:**
+```typescript
+import { schemaToInquirer } from 'inquirer-form'
+
+const questions = schemaToInquirer(schema, {
+  includeDisabled: false
+})
+```
+
+#### createInquirerSampleControls(t)
+
+Create sample form controls.
+
+**Parameters:**
+- `t: (key: string) => string` - i18n translation function
+
+**Returns:**
+- `SchemaNode[]` - Array of schema nodes
+
+**Example:**
+```typescript
+import { createInquirerSampleControls } from 'inquirer-form'
+
+const controls = createInquirerSampleControls((key) => key)
+engine.getSchema().controls = controls
+```
+
+### Types
+
+#### InquirerPromptType
+
+Supported Inquirer prompt types.
+
+```typescript
+type InquirerPromptType =
+  | 'input'      // Text input
+  | 'number'     // Number input
+  | 'confirm'    // Confirmation (yes/no)
+  | 'list'       // Single choice list
+  | 'rawlist'    // Raw list
+  | 'expand'     // Expand choice
+  | 'checkbox'   // Multiple choice
+  | 'password'   // Password input
+  | 'editor'     // Multi-line editor
+```
+
+#### InquirerQuestion
+
+Inquirer question object interface.
+
+```typescript
+interface InquirerQuestion {
+  type: InquirerPromptType
+  name: string
+  message: string
+  default?: any
+  prefix?: string
+  suffix?: string
+  pageSize?: number
+  loop?: boolean
+  mask?: string | boolean
+  choices?: InquirerChoice[]
+  whenExpression?: string
+  validateExpression?: string
+  filterExpression?: string
+  transformerExpression?: string
+  metadata?: Record<string, any>
+}
+```
+
+#### InquirerChoice
+
+Choice interface (for list, checkbox, etc.).
+
+```typescript
+interface InquirerChoice {
+  name: string    // Display text
+  value: string   // Actual value
+  short?: string  // Short description
+}
+```
+
+##  Built-in Controls
+
+| Control Type | Description | Inquirer Type |
+|-------------|-------------|---------------|
+| Input | Text input field | `input` |
+| Password | Password input field | `password` |
+| Number | Number input field | `number` |
+| Confirm | Confirmation box | `confirm` |
+| List | Single choice list | `list` |
+| RawList | Raw list | `rawlist` |
+| Expand | Expand choice | `expand` |
+| Checkbox | Multiple choice | `checkbox` |
+| Editor | Multi-line editor | `editor` |
+
+##  Advanced Usage
+
+### Custom Controls
+
+```typescript
+import { registry } from 'agilebuilder-form'
+import type { ControlMeta } from 'agilebuilder-form'
+
+const customControl: ControlMeta = {
+  type: 'custom-input',
+  label: 'Custom Input',
+  component: CustomInputComponent,
+  initialSchema: () => ({
+    id: generateId(),
+    type: 'custom-input',
+    field: '',
+    props: {}
+  })
 }
+
+// Register custom control
+registry.register(customControl)
+```
+
+### Expression Support
+
+Schema supports various expression fields for dynamic control:
+
+```typescript
+{
+  type: 'input',
+  field: 'email',
+  props: {
+    message: 'Enter your email',
+    // Conditional display
+    whenExpression: "return answers.needEmail === true",
+    // Validation
+    validateExpression: "return /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(input) || 'Please enter a valid email'",
+    // Filter
+    filterExpression: "return input.trim().toLowerCase()",
+    // Transform display
+    transformerExpression: "return input.replace(/@.*/, '@***')"
+  }
+}
+```
+
+### Integration with Inquirer.js
+
+Complete CLI integration example:
+
+```typescript
+import inquirer from 'inquirer'
+import { schemaToInquirer } from 'inquirer-form'
+import type { FormSchema } from 'agilebuilder-form'
+
+// Load schema from file or API
+const schema: FormSchema = require('./form-schema.json')
+
+// Convert to Inquirer questions
+const questions = schemaToInquirer(schema)
+
+// Process expressions (convert strings to functions)
+const processedQuestions = questions.map(q => ({
+  ...q,
+  when: q.whenExpression 
+    ? new Function('answers', q.whenExpression) 
+    : undefined,
+  validate: q.validateExpression
+    ? new Function('input', 'answers', q.validateExpression)
+    : undefined,
+  filter: q.filterExpression
+    ? new Function('input', 'answers', q.filterExpression)
+    : undefined,
+  transformer: q.transformerExpression
+    ? new Function('input', 'answers', 'flags', q.transformerExpression)
+    : undefined
+}))
+
+// Execute prompts
+const answers = await inquirer.prompt(processedQuestions)
+console.log('User input:', answers)
+```
+
+##  Development
+
+### Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server (Playground) |
+| `npm run build` | Build for production |
+| `npm run type-check` | TypeScript type checking |
+| `npm run test:unit` | Run unit tests |
+| `npm run docs:dev` | Start documentation dev server |
+| `npm run docs:build` | Build documentation |
+
+### Build Output
+
+After running `npm run build`, the following files will be generated:
+
 ```
+dist/
+ inquirer-form.es.js      # ES Module
+ inquirer-form.umd.js     # UMD Module
+ inquirer-form.css        # Stylesheet
+ index.d.ts               # TypeScript declarations
+```
+
+### Publishing to npm
 
-## 许可证
+1. Make sure you're logged in to npm
+2. Update version: `npm version patch|minor|major`
+3. Build: `npm run build`
+4. Publish: `npm publish --access public`
+
+##  Related Projects
+
+- [agilebuilder-form](https://github.com/yjkjdev/agilebuilder-form) - Underlying form engine
+- [Inquirer.js](https://github.com/SBoudrias/Inquirer.js/) - CLI interaction library
+- [Element Plus](https://element-plus.org/) - UI component library
+- [Vue 3](https://vuejs.org/) - Progressive JavaScript framework
+
+##  License
 
 [MIT](./LICENSE)
+
+##  Contributing
+
+Issues and Pull Requests are welcome!
+
+##  Contact
+
+For questions or suggestions, please contact us through GitHub Issues.