{"_id":"@aivue/guided-form","name":"@aivue/guided-form","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aivue/guided-form","version":"1.0.0","description":"AI-assisted guided form builder - Transform form schemas into one-question-at-a-time conversational experiences","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./dist/guided-form.css":"./dist/guided-form.css"},"scripts":{"build":"npm run clean && vite build","dev":"vite build --watch","clean":"rm -rf dist","prepublishOnly":"npm run build"},"keywords":["vue","form","guided-form","conversational-form","ai-form","form-builder","one-question-at-a-time","wizard","multi-step-form","ai-assist","form-schema","validation","save-resume"],"author":{"name":"reachbrt"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/reachbrt/vueai.git","directory":"packages/guided-form"},"homepage":"https://github.com/reachbrt/vueai#readme","bugs":{"url":"https://github.com/reachbrt/vueai/issues"},"publishConfig":{"access":"public"},"peerDependencies":{"@aivue/core":"^1.3.5","vue":"^2.6.0 || ^3.0.0"},"dependencies":{"vue-demi":"^0.14.10"},"devDependencies":{"@types/node":"^20.16.0","@vitejs/plugin-vue":"^5.0.0","autoprefixer":"^10.4.20","postcss":"^8.4.49","tailwindcss":"^3.4.17","typescript":"^5.3.0","vite":"^6.3.5","vite-plugin-dts":"^4.5.3","vue":"^3.5.0"},"_id":"@aivue/guided-form@1.0.0","gitHead":"71f713bf1b7bc1ae27a7f47fe4eb5729c1bd09ec","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-yxi5lL/YCSeq8QLRs5HsolGn1Fx9vdHMgZ4lfcTezoDZxGSYeegzpiWE/ymQznpNaL3UePOBhNd/fVfi96O9Hw==","shasum":"2b33ecbd1e302eac86261711f2ff831fb5652167","tarball":"https://registry.npmjs.org/@aivue/guided-form/-/guided-form-1.0.0.tgz","fileCount":8,"unpackedSize":216811,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGwKKbYxuFD5VpJKOo60HYBXZkQpoHpZltmTmR/peMBUAiEA5UK6pKUD5pnsdhE7OEPJrlbrGpUTqhtELl9tpfolKlc="}]},"_npmUser":{"name":"aivue","email":"reachbrt@gmail.com"},"directories":{},"maintainers":[{"name":"aivue","email":"reachbrt@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/guided-form_1.0.0_1769241631627_0.5619227317129998"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-24T08:00:31.488Z","1.0.0":"2026-01-24T08:00:31.765Z","modified":"2026-01-24T08:00:32.089Z"},"maintainers":[{"name":"aivue","email":"reachbrt@gmail.com"}],"description":"AI-assisted guided form builder - Transform form schemas into one-question-at-a-time conversational experiences","homepage":"https://github.com/reachbrt/vueai#readme","keywords":["vue","form","guided-form","conversational-form","ai-form","form-builder","one-question-at-a-time","wizard","multi-step-form","ai-assist","form-schema","validation","save-resume"],"repository":{"type":"git","url":"git+https://github.com/reachbrt/vueai.git","directory":"packages/guided-form"},"author":{"name":"reachbrt"},"bugs":{"url":"https://github.com/reachbrt/vueai/issues"},"license":"MIT","readme":"# @aivue/guided-form\n\n> 🎯 Transform form schemas into AI-assisted, one-question-at-a-time conversational experiences\n\n[![npm version](https://img.shields.io/npm/v/@aivue/guided-form.svg)](https://www.npmjs.com/package/@aivue/guided-form)\n[![npm downloads](https://img.shields.io/npm/dm/@aivue/guided-form.svg)](https://www.npmjs.com/package/@aivue/guided-form)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## ✨ Features\n\n### 🎨 **Core Capabilities**\n- **📝 One-Question-at-a-Time Flow** - Guided conversational form experience\n- **🤖 AI-Powered Assistance** - Hints, explanations, examples, and validation\n- **⌨️ Smart Keyboard Navigation** - Enter to advance, numeric shortcuts, Tab navigation\n- **📱 Mobile-First Design** - Large tap targets, sticky buttons, responsive layout\n- **💾 Save & Resume** - Multiple persistence adapters (localStorage, sessionStorage, custom)\n- **🔄 Conditional Logic** - Dynamic form flow based on user answers\n- **✅ Advanced Validation** - Field-level and step-level validation with friendly messages\n- **🎯 Progress Tracking** - Visual progress indicators and step completion\n- **🌐 Vue 2 & 3 Compatible** - Works seamlessly with Vue 2.6+ and Vue 3.x\n\n### 🎨 **Rich Input Types**\n- Text, Textarea, Number, Email, Tel, URL\n- Date, Time, DateTime\n- Select, Multi-Select, Radio, Checkbox\n- Rating, File Upload, Yes/No Chips\n- Slider, Color Picker\n\n### 🤖 **AI Integration**\n- **OpenAI** - GPT-3.5, GPT-4\n- **Anthropic** - Claude models\n- **Custom Providers** - Bring your own AI endpoint\n\n## 📦 Installation\n\n```bash\nnpm install @aivue/guided-form @aivue/core\n```\n\n## 🚀 Quick Start\n\n### Vue 3\n\n```vue\n<template>\n  <div>\n    <GuidedFormContainer\n      :currentStep=\"currentStep\"\n      :currentStepIndex=\"currentStepIndex\"\n      :totalSteps=\"totalSteps\"\n      :progress=\"progress\"\n      :canGoBack=\"canGoBack\"\n      :canGoNext=\"canGoNext\"\n      :isComplete=\"isComplete\"\n      :isLoading=\"isLoading\"\n      :validationErrors=\"validationErrors\"\n      :aiEnabled=\"true\"\n      :showProgress=\"true\"\n      @next=\"goToNext\"\n      @previous=\"goToPrevious\"\n      @change=\"setAnswer\"\n      @getHint=\"handleGetHint\"\n    />\n  </div>\n</template>\n\n<script setup>\nimport { useGuidedForm } from '@aivue/guided-form';\n\nconst schema = {\n  id: 'contact-form',\n  name: 'Contact Information',\n  version: '1.0.0',\n  status: 'published',\n  steps: [\n    {\n      id: 'step-1',\n      type: 'question',\n      field: {\n        fieldId: 'name',\n        fieldType: 'text',\n        required: true,\n      },\n      ui: {\n        title: \"What's your name?\",\n        subtitle: 'We\\'d love to know who we\\'re talking to',\n        helpText: 'Enter your full name',\n      },\n    },\n    {\n      id: 'step-2',\n      type: 'question',\n      field: {\n        fieldId: 'email',\n        fieldType: 'email',\n        required: true,\n        validationRules: [\n          { type: 'email', message: 'Please enter a valid email address' }\n        ],\n      },\n      ui: {\n        title: \"What's your email address?\",\n        subtitle: 'We\\'ll use this to get in touch',\n      },\n    },\n  ],\n  settings: {\n    aiFlags: {\n      enabled: true,\n      provider: 'openai',\n      apiKey: 'your-api-key',\n      model: 'gpt-3.5-turbo',\n    },\n    keyboard: {\n      enterToNext: true,\n      numericShortcuts: true,\n      tabNavigation: true,\n    },\n  },\n};\n\nconst {\n  currentStep,\n  currentStepIndex,\n  totalSteps,\n  progress,\n  canGoBack,\n  canGoNext,\n  isComplete,\n  isLoading,\n  validationErrors,\n  goToNext,\n  goToPrevious,\n  setAnswer,\n  getAIHint,\n} = useGuidedForm({ schema });\n\nconst handleGetHint = async (type) => {\n  const hints = await getAIHint(type);\n  console.log('AI Hints:', hints);\n};\n</script>\n```\n\n### Vue 2\n\n```vue\n<template>\n  <div>\n    <GuidedFormContainer\n      :currentStep=\"currentStep\"\n      :currentStepIndex=\"currentStepIndex\"\n      :totalSteps=\"totalSteps\"\n      :progress=\"progress\"\n      :canGoBack=\"canGoBack\"\n      :canGoNext=\"canGoNext\"\n      :isComplete=\"isComplete\"\n      :isLoading=\"isLoading\"\n      :validationErrors=\"validationErrors\"\n      @next=\"goToNext\"\n      @previous=\"goToPrevious\"\n      @change=\"setAnswer\"\n    />\n  </div>\n</template>\n\n<script>\nimport { useGuidedForm } from '@aivue/guided-form';\n\nexport default {\n  setup() {\n    const schema = { /* same as above */ };\n    \n    return useGuidedForm({ schema });\n  },\n};\n</script>\n```\n\n## 📚 Documentation\n\n### Schema Definition\n\nThe form schema is a JSON object that defines the entire form structure:\n\n```typescript\ninterface FormSchema {\n  id: string;\n  name: string;\n  version: string;\n  status: 'draft' | 'published' | 'archived';\n  steps: Step[];\n  settings?: FormSettings;\n}\n```\n\n### Step Types\n\nEach step can be one of four types:\n\n- **question** - A form field that collects user input\n- **info** - Informational content (no input required)\n- **group** - A group of related questions\n- **end** - Final step with completion message\n\n### Field Types\n\nAll supported input types:\n\n| Type | Description | Example |\n|------|-------------|---------|\n| `text` | Single-line text input | Name, title |\n| `textarea` | Multi-line text input | Comments, description |\n| `number` | Numeric input | Age, quantity |\n| `email` | Email address | user@example.com |\n| `tel` | Phone number | +1-555-0100 |\n| `url` | Website URL | https://example.com |\n| `date` | Date picker | 2024-01-24 |\n| `time` | Time picker | 14:30 |\n| `datetime` | Date and time | 2024-01-24 14:30 |\n| `select` | Dropdown selection | Country, category |\n| `multiselect` | Multiple selections | Tags, interests |\n| `radio` | Single choice from options | Gender, size |\n| `checkbox` | Multiple choices | Preferences |\n| `rating` | Star rating | 1-5 stars |\n| `file` | File upload | Documents, images |\n| `yesno` | Yes/No chips | Boolean questions |\n| `slider` | Range slider | Volume, price range |\n| `color` | Color picker | Theme color |\n\n### Conditional Logic\n\nCreate dynamic forms that adapt based on user answers:\n\n```typescript\n{\n  id: 'step-3',\n  type: 'question',\n  field: {\n    fieldId: 'company',\n    fieldType: 'text',\n  },\n  ui: {\n    title: \"What company do you work for?\",\n  },\n  logic: {\n    visibilityConditions: [\n      {\n        fieldId: 'employment',\n        operator: 'equals',\n        value: 'employed',\n      }\n    ],\n    conditionalJumps: [\n      {\n        conditions: [\n          {\n            fieldId: 'company',\n            operator: 'isEmpty',\n          }\n        ],\n        logic: 'and',\n        nextStepId: 'step-5', // Skip step 4\n      }\n    ],\n  },\n}\n```\n\n### AI Assistance\n\nEnable AI-powered help for your forms:\n\n```typescript\nsettings: {\n  aiFlags: {\n    enabled: true,\n    provider: 'openai', // or 'anthropic' or 'custom'\n    apiKey: process.env.VITE_OPENAI_API_KEY,\n    model: 'gpt-3.5-turbo',\n    // For custom providers:\n    customEndpoint: 'https://your-api.com/chat',\n  },\n}\n```\n\nAI assistance types:\n- **explain** - Get a simple explanation of the question\n- **rewrite** - Rewrite the question in simpler language\n- **example** - Get example answers\n- **validate** - Get AI feedback on user's answer\n\n### Keyboard Navigation\n\nBuilt-in keyboard shortcuts for power users:\n\n```typescript\nsettings: {\n  keyboard: {\n    enterToNext: true,        // Press Enter to go to next step\n    numericShortcuts: true,   // Press 1-9 to select options\n    tabNavigation: true,      // Tab/Shift+Tab to navigate\n  },\n}\n```\n\n### Save & Resume\n\nMultiple persistence options:\n\n```typescript\nimport {\n  LocalStoragePersistenceAdapter,\n  SessionStoragePersistenceAdapter,\n  MemoryPersistenceAdapter,\n  CustomPersistenceAdapter,\n} from '@aivue/guided-form';\n\n// LocalStorage (persists across sessions)\nconst persistence = new LocalStoragePersistenceAdapter('my-form');\n\n// SessionStorage (cleared when tab closes)\nconst persistence = new SessionStoragePersistenceAdapter('my-form');\n\n// Memory (lost on page refresh)\nconst persistence = new MemoryPersistenceAdapter();\n\n// Custom (your own implementation)\nconst persistence = new CustomPersistenceAdapter(\n  async (sessionId, state) => { /* save */ },\n  async (sessionId) => { /* load */ },\n  async (sessionId) => { /* delete */ }\n);\n\n// Use with composable\nconst form = useGuidedForm({\n  schema,\n  persistenceAdapter: persistence,\n  sessionId: 'user-123',\n});\n\n// Save progress\nawait form.saveProgress();\n\n// Resume session\nawait form.resumeSession('resume-token');\n```\n\n### Validation\n\nComprehensive validation rules:\n\n```typescript\nfield: {\n  fieldId: 'password',\n  fieldType: 'text',\n  required: true,\n  validationRules: [\n    { type: 'minLength', value: 8, message: 'Password must be at least 8 characters' },\n    { type: 'pattern', value: '^(?=.*[A-Z])(?=.*[0-9])', message: 'Must contain uppercase and number' },\n  ],\n}\n```\n\nAvailable validation types:\n- `required` - Field must have a value\n- `minLength` - Minimum string length\n- `maxLength` - Maximum string length\n- `min` - Minimum numeric value\n- `max` - Maximum numeric value\n- `pattern` - Regex pattern match\n- `email` - Valid email format\n- `url` - Valid URL format\n\n## 🎨 Styling\n\nThe package includes Tailwind CSS styles. You can customize the theme:\n\n```javascript\n// tailwind.config.js\nmodule.exports = {\n  theme: {\n    extend: {\n      colors: {\n        primary: {\n          50: '#f0f9ff',\n          // ... your colors\n          900: '#0c4a6e',\n        },\n      },\n    },\n  },\n};\n```\n\n## 🔧 API Reference\n\n### useGuidedForm(options)\n\nMain composable for form functionality.\n\n**Options:**\n- `schema` - Form schema object (required)\n- `hooks` - Event hooks (optional)\n- `persistenceAdapter` - Storage adapter (optional)\n- `sessionId` - Session identifier (optional)\n- `resumeToken` - Token to resume session (optional)\n- `initialState` - Initial form state (optional)\n\n**Returns:**\n- `currentStep` - Current step object\n- `currentStepIndex` - Current step index (0-based)\n- `totalSteps` - Total number of steps\n- `answers` - All user answers\n- `isComplete` - Whether form is complete\n- `isLoading` - Loading state\n- `validationErrors` - Current validation errors\n- `formState` - Complete form state\n- `schema` - Form schema\n- `progress` - Progress percentage (0-100)\n- `canGoBack` - Whether user can go back\n- `canGoNext` - Whether user can go forward\n- `goToNext()` - Navigate to next step\n- `goToPrevious()` - Navigate to previous step\n- `goToStep(stepId)` - Navigate to specific step\n- `setAnswer(fieldId, value)` - Set field answer\n- `getAnswer(fieldId)` - Get field answer\n- `clearAnswer(fieldId)` - Clear field answer\n- `validateCurrentStep()` - Validate current step\n- `validateField(fieldId, value)` - Validate specific field\n- `getAIHint(type)` - Get AI assistance\n- `saveProgress()` - Save current progress\n- `resumeSession(token)` - Resume from token\n- `resetForm()` - Reset form to initial state\n\n## 📄 License\n\nMIT © [reachbrt](https://github.com/reachbrt)\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## 🙏 Credits\n\nCreated by [Bharat Kumar Subramanian](https://www.linkedin.com/in/bharatkumarsubramanian/)\n\nSpecial thanks to:\n- **Manoj** - Main guidance and mentorship\n- **Thiru** - AI sessions and teaching\n\n---\n\nPart of the [@aivue](https://github.com/reachbrt/vueai) ecosystem - AI-powered Vue.js components\n\n\n","readmeFilename":"README.md","_rev":"1-a531cf76b410450599ba5330fad40d89"}