{"_id":"@altx-labs/react-typed-form-kit","name":"@altx-labs/react-typed-form-kit","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@altx-labs/react-typed-form-kit","version":"0.0.1","description":"A modern, accessible, and performant type-safe form library for React with JSON-driven forms","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.js"},"./dist/styles.css":"./dist/styles/base.css","./styles.css":"./dist/styles/base.css","./styles":"./dist/styles/base.css"},"peerDependencies":{"react":"^18.0.0 || ^19.0.0","react-dom":"^18.0.0 || ^19.0.0"},"dependencies":{"clsx":"^2.1.1","debug":"^4.4.1","framer-motion":"^11.15.0","lucide-react":"^0.542.0","react-icons":"^5.5.0"},"devDependencies":{"@types/debug":"^4.1.12","@types/react":"^19.1.0","@types/react-dom":"^19.1.0","@typescript-eslint/eslint-plugin":"^8.21.0","@typescript-eslint/parser":"^8.21.0","eslint":"^9.18.0","eslint-plugin-react":"^7.37.3","eslint-plugin-react-hooks":"^5.1.0","tsup":"^8.3.5","typescript":"^5.7.3"},"publishConfig":{"access":"public"},"sideEffects":["**/*.css"],"style":"./dist/styles/base.css","repository":{"type":"git","url":"git+https://github.com/altx-labs/piaf.git"},"keywords":["react","forms","typescript","json-forms","form-builder","accessible","typeform"],"author":{"name":"William Li"},"license":"MIT","scripts":{"build":"tsup","dev":"tsup --watch","type-check":"tsc --noEmit","lint":"eslint src --ext .ts,.tsx"},"_id":"@altx-labs/react-typed-form-kit@0.0.1","bugs":{"url":"https://github.com/altx-labs/piaf/issues"},"homepage":"https://github.com/altx-labs/piaf#readme","_integrity":"sha512-v+aI0PiY+UXTwbo2+h79uVU88AkFa4wCgGMOsnN8W2KfVMaXjhx/x1spqfgh+UlphwMlOZVpIjJOYhCMWF8H2g==","_resolved":"/tmp/4b5e1ca42e6389235cf64ad8a262010e/altx-labs-react-typed-form-kit-0.0.1.tgz","_from":"file:altx-labs-react-typed-form-kit-0.0.1.tgz","_nodeVersion":"20.19.4","_npmVersion":"10.8.2","dist":{"integrity":"sha512-v+aI0PiY+UXTwbo2+h79uVU88AkFa4wCgGMOsnN8W2KfVMaXjhx/x1spqfgh+UlphwMlOZVpIjJOYhCMWF8H2g==","shasum":"b4f885d9bcf484cd6151a79a97e027c7bc2c3030","tarball":"https://registry.npmjs.org/@altx-labs/react-typed-form-kit/-/react-typed-form-kit-0.0.1.tgz","fileCount":12,"unpackedSize":692795,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCZRamgtndshjBUz5IQLJE/hdVAVk9TeD6bh6vYYAhhnQIgP1BAKsk71p7K9iKIOV88Ut6M4ulNlLhpXwG1pDVkzNE="}]},"_npmUser":{"name":"wiiiimm","email":"email@wiiiimm.codes"},"directories":{},"maintainers":[{"name":"wiiiimm","email":"email@wiiiimm.codes"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/react-typed-form-kit_0.0.1_1757407066696_0.44093599925371474"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-09T08:37:46.610Z","0.0.1":"2025-09-09T08:37:46.896Z","modified":"2025-09-09T08:37:47.181Z"},"maintainers":[{"name":"wiiiimm","email":"email@wiiiimm.codes"}],"description":"A modern, accessible, and performant type-safe form library for React with JSON-driven forms","homepage":"https://github.com/altx-labs/piaf#readme","keywords":["react","forms","typescript","json-forms","form-builder","accessible","typeform"],"repository":{"type":"git","url":"git+https://github.com/altx-labs/piaf.git"},"author":{"name":"William Li"},"bugs":{"url":"https://github.com/altx-labs/piaf/issues"},"license":"MIT","readme":"# React Typed Form Kit\n\nA modern, accessible, and performant type-safe form library for React with JSON-driven forms. Build beautiful, multi-step forms with animations, validation, and internationalization support.\n\n[![NPM Version](https://img.shields.io/npm/v/react-typed-form-kit)](https://www.npmjs.com/package/react-typed-form-kit)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue)](https://www.typescriptlang.org/)\n\n## ✨ Features\n\n- 📋 **JSON-Driven Forms** - Define forms using JSON configuration\n- 🎭 **TypeScript First** - Full type safety and inference\n- 🎨 **Beautiful UI** - Modern design with smooth animations\n- 📱 **Responsive** - Works on all device sizes\n- ♿ **Accessible** - WCAG 2.1 compliant\n- 🌍 **Internationalization** - Built-in i18n support\n- 🔄 **Auto-Save** - Draft functionality with localStorage\n- 📊 **Progress Tracking** - Visual progress indicators\n- 🎯 **Validation** - Comprehensive form validation\n- 🖼️ **Background Images** - Support for form backgrounds\n- 📖 **Chapter Support** - Multi-section forms\n- 🎪 **Nested Questions** - Conditional question display\n\n## 📦 Installation\n\n```bash\nnpm install react-typed-form-kit\n# or\nyarn add react-typed-form-kit\n# or\npnpm add react-typed-form-kit\n```\n\n### CSS Import\n\nImport the CSS file in your application:\n\n```tsx\nimport 'react-typed-form-kit/styles.css';\n```\n\n## 🚀 Quick Start\n\n```tsx\nimport React from 'react';\nimport { FormRenderer, FormDefinition } from 'react-typed-form-kit';\nimport 'react-typed-form-kit/styles.css';\n\nconst formDefinition: FormDefinition = {\n  meta: {\n    id: 'contact-form',\n    title: { en: 'Contact Form', zh: '联系表单' },\n    description: { en: 'Get in touch with us', zh: '与我们联系' },\n    category: 'contact',\n    estimatedTime: 3,\n    totalQuestions: 3,\n    languages: ['en', 'zh'],\n  },\n  config: {\n    showProgressBar: true,\n    allowBackNavigation: true,\n  },\n  questions: {\n    name: {\n      type: 'text',\n      title: { en: 'Your Name', zh: '您的姓名' },\n      validation: { required: true, minLength: 2 },\n    },\n    email: {\n      type: 'email',\n      title: { en: 'Email Address', zh: '电子邮箱' },\n      validation: { required: true },\n    },\n    message: {\n      type: 'textarea',\n      title: { en: 'Message', zh: '消息' },\n      validation: { required: true, minLength: 10 },\n    },\n  },\n};\n\nfunction App() {\n  const handleSubmit = (data: any) => {\n    console.log('Form submitted:', data);\n  };\n\n  return (\n    <FormRenderer\n      definition={formDefinition}\n      onSubmit={handleSubmit}\n      language=\"en\"\n    />\n  );\n}\n\nexport default App;\n```\n\n## 📚 Core Concepts\n\n### Form Definition\n\nA form definition is a JSON object that describes your form structure:\n\n```tsx\ninterface FormDefinition {\n  meta: FormMeta;           // Form metadata\n  config: FormConfig;       // Form configuration\n  questions: Questions;     // Form questions\n  chapters?: Chapter[];     // Optional chapters for multi-section forms\n}\n```\n\n### Question Types\n\nSupported question types:\n\n- `text` - Single-line text input\n- `textarea` - Multi-line text input\n- `email` - Email input with validation\n- `phone` - Phone number input\n- `number` - Numeric input\n- `radio` - Single choice from options\n- `checkbox` - Multiple choice from options\n- `nested` - Conditional questions based on parent answers\n\n### Validation\n\nBuilt-in validation rules:\n\n```tsx\ninterface ValidationRules {\n  required?: boolean;\n  minLength?: number;\n  maxLength?: number;\n  min?: number;\n  max?: number;\n  pattern?: string;\n  email?: boolean;\n  phone?: boolean;\n  custom?: (value: any) => string | undefined;\n}\n```\n\n## 🎨 Styling & Theming\n\n### CSS Custom Properties\n\nCustomize the appearance using CSS custom properties:\n\n```css\n:root {\n  --form-primary: #3b82f6;\n  --form-primary-hover: #2563eb;\n  --form-background: #ffffff;\n  --form-surface: #f8fafc;\n  --form-text-primary: #1f2937;\n  --form-text-secondary: #6b7280;\n  --form-border: #e5e7eb;\n  --form-error: #ef4444;\n  --form-success: #10b981;\n  \n  --form-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;\n  --form-font-family-serif: Georgia, 'Times New Roman', serif;\n  \n  --form-border-radius: 0.5rem;\n  --form-transition-fast: 150ms ease-in-out;\n  --form-transition-normal: 250ms ease-in-out;\n}\n```\n\n### Background Images\n\nAdd background images to your forms:\n\n```tsx\nconst formWithBackground: FormDefinition = {\n  // ... other config\n  questions: {\n    welcome: {\n      type: 'text',\n      title: { en: 'Welcome!' },\n      background: {\n        image: '/path/to/image.jpg',\n        position: 'left' // 'left', 'right', or 'default'\n      }\n    }\n  }\n};\n```\n\n## 🌍 Internationalization\n\nSupport multiple languages:\n\n```tsx\n// Define content in multiple languages\nconst multiLangForm: FormDefinition = {\n  meta: {\n    title: {\n      en: 'Contact Form',\n      zh: '联系表单'\n    },\n    // ...\n  },\n  questions: {\n    name: {\n      type: 'text',\n      title: {\n        en: 'What is your name?',\n        zh: '您的姓名是什么？'\n      },\n      placeholder: {\n        en: 'Enter your full name',\n        zh: '请输入您的全名'\n      }\n    }\n  }\n};\n\n// Use with language switching\nfunction App() {\n  const [language, setLanguage] = useState<Language>('en');\n  \n  return (\n    <FormRenderer\n      definition={multiLangForm}\n      language={language}\n      onLanguageChange={setLanguage}\n      onSubmit={handleSubmit}\n    />\n  );\n}\n```\n\n## 🔄 Advanced Features\n\n### Chapter-Based Forms\n\nCreate multi-section forms:\n\n```tsx\nconst chapterForm: FormDefinition = {\n  meta: { /* ... */ },\n  config: { /* ... */ },\n  chapters: [\n    {\n      id: 'personal',\n      title: { en: 'Personal Information' },\n      questions: {\n        name: { /* ... */ },\n        email: { /* ... */ }\n      }\n    },\n    {\n      id: 'preferences',\n      title: { en: 'Preferences' },\n      questions: {\n        newsletter: { /* ... */ },\n        notifications: { /* ... */ }\n      }\n    }\n  ]\n};\n```\n\n### Nested Questions\n\nShow questions conditionally:\n\n```tsx\nconst conditionalForm: FormDefinition = {\n  questions: {\n    hasExperience: {\n      type: 'radio',\n      title: { en: 'Do you have experience?' },\n      options: [\n        {\n          value: 'yes',\n          label: { en: 'Yes' },\n          nestedQuestions: [\n            {\n              id: 'yearsExperience',\n              type: 'number',\n              title: { en: 'How many years?' },\n              validation: { required: true, min: 1 }\n            }\n          ]\n        },\n        {\n          value: 'no',\n          label: { en: 'No' }\n        }\n      ]\n    }\n  }\n};\n```\n\n### Draft Links & Auto-Save\n\nEnable draft functionality:\n\n```tsx\n<FormRenderer\n  definition={formDefinition}\n  onSubmit={handleSubmit}\n  config={{\n    autoSave: true,\n    enableDraftLinks: true\n  }}\n/>\n```\n\n## 🎣 Hooks\n\n### useFormState\n\nManage form state manually:\n\n```tsx\nimport { useFormState } from 'react-typed-form-kit';\n\nfunction CustomForm() {\n  const {\n    state,\n    setAnswer,\n    nextQuestion,\n    previousQuestion,\n    generateDraftLink\n  } = useFormState(formDefinition);\n\n  return (\n    <div>\n      {/* Custom form implementation */}\n    </div>\n  );\n}\n```\n\n### useKeyboardNavigation\n\nAdd keyboard shortcuts:\n\n```tsx\nimport { useKeyboardNavigation } from 'react-typed-form-kit';\n\nfunction App() {\n  useKeyboardNavigation({\n    onNext: handleNext,\n    onPrevious: handlePrevious,\n    onSubmit: handleSubmit\n  });\n\n  return <FormRenderer /* ... */ />;\n}\n```\n\n## 🎯 Validation\n\n### Built-in Validators\n\n```tsx\nconst validatedQuestion = {\n  type: 'text',\n  title: { en: 'Username' },\n  validation: {\n    required: true,\n    minLength: 3,\n    maxLength: 20,\n    pattern: '^[a-zA-Z0-9_]+$' // Regex pattern\n  }\n};\n```\n\n### Custom Validation\n\n```tsx\nconst customValidation = {\n  type: 'text',\n  title: { en: 'Password' },\n  validation: {\n    required: true,\n    custom: (value: string) => {\n      if (value.length < 8) return 'Password must be at least 8 characters';\n      if (!/[A-Z]/.test(value)) return 'Password must contain uppercase letter';\n      if (!/[0-9]/.test(value)) return 'Password must contain a number';\n      return undefined; // Valid\n    }\n  }\n};\n```\n\n## 📱 Responsive Design\n\nThe form automatically adapts to different screen sizes:\n\n- **Desktop**: Full-width layout with side navigation\n- **Tablet**: Optimized for touch interactions\n- **Mobile**: Single-column layout with bottom navigation\n\n## ♿ Accessibility\n\nBuilt with accessibility in mind:\n\n- ARIA labels and descriptions\n- Keyboard navigation support\n- Screen reader friendly\n- High contrast support\n- Focus management\n- Error announcement\n\n## 🔧 API Reference\n\n### FormRenderer Props\n\n```tsx\ninterface FormKitProps {\n  definition: FormDefinition;\n  onSubmit: (data: Record<string, any>) => void;\n  language?: Language;\n  initialValues?: Record<string, any>;\n  draftId?: string;\n  className?: string;\n  onLanguageChange?: (language: Language) => void;\n  onProgressChange?: (progress: number) => void;\n}\n```\n\n### Form Definition Schema\n\nSee the [Wiki](./wiki/README.md) for complete schema documentation.\n\n## 🤝 Contributing\n\nContributions are welcome! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.\n\n## 📄 License\n\nMIT © [William Li](https://github.com/williamli)\n\n## 🔗 Links\n\n- [Documentation](./wiki/README.md)\n- [Examples](./examples)\n- [GitHub Repository](https://github.com/altx-labs/piaf)\n- [NPM Package](https://www.npmjs.com/package/react-typed-form-kit)\n\n---\n\nMade with ❤️ by [AltX Labs](https://github.com/altx-labs)","readmeFilename":"README.md","_rev":"1-a5b7a9794c3659f617529cf81e1aa491"}