@dmitryvim/form-builder 0.1.37 → 0.1.38

package/docs/REQUIREMENTS.md

@@ -1,313 +0,0 @@
-# Product & Business Requirements
-
-Core requirements and specifications for the Form Builder library.
-
-## Product Overview
-
-**Form Builder** transforms JSON schemas into dynamic, interactive web forms with real-time validation and structured data output. Designed as a framework-agnostic, zero-dependency library for easy integration.
-
-**Primary Goal**: Provide a reusable form generation solution that eliminates custom form development overhead.
-
-## Business Requirements
-
-### Core Value Propositions
-
-1. **Rapid Form Development**: Schema → Form in minutes, not hours
-2. **Consistent UX**: Standardized form behavior across applications
-3. **Zero Dependencies**: No framework lock-in or bundle bloat
-4. **File Upload Ready**: Built-in support for modern file workflows
-5. **Deployment Flexibility**: CDN, NPM, or self-hosted options
-
-### Target Users
-
-- **Developers**: Need forms for SPA applications
-- **Product Teams**: Require consistent form experiences
-- **Startups**: Want rapid prototyping capabilities
-- **Enterprise**: Need standardized form solutions
-
-## Functional Requirements
-
-### 1. Form Generation Engine
-
-**MUST support field types:**
-
-- `text` - Single line input with validation
-- `textarea` - Multi-line text input
-- `number` - Numeric input with constraints
-- `select` - Dropdown with options
-- `file` - Single file upload with preview
-- `files` - Multiple file upload with limits
-- `group` - Nested objects with repeat support
-
-```javascript
-// Example schema
-{
-  "version": "0.3",
-  "title": "Asset Upload",
-  "elements": [
-    {
-      "type": "files",
-      "key": "assets",
-      "label": "Images",
-      "maxCount": 10,
-      "accept": { "extensions": ["jpg", "png"] }
-    }
-  ]
-}
-```
-
-### 2. Validation System
-
-**MUST provide:**
-
-- Real-time field validation
-- Required field checking
-- String length limits (minLength/maxLength)
-- Numeric ranges (min/max)
-- Pattern matching (regex)
-- File type restrictions
-- Custom validation rules
-
-**MUST support:**
-
-- Form submission with full validation
-- Draft saving without validation
-- Field-level error display
-
-### 3. File Upload System
-
-**Upload Handler Requirements:**
-
-```javascript
-// Handler MUST return resource ID for download/submission
-uploadHandler: async (file) => {
-  // Upload logic...
-  return resourceId; // NOT file URL
-};
-```
-
-**MUST provide:**
-
-- Visual file previews (thumbnails + icons)
-- Upload progress indicators
-- Individual file removal
-- Drag & drop support
-- File metadata display (name, size, type)
-
-### 4. Form Modes
-
-**Submission Mode** (default):
-
-- Full editing capabilities
-- Real-time validation
-- Submit button requires all validation to pass
-
-**Read-Only Mode**:
-
-- Display form data without editing
-- Show file download links
-- Disable all form interactions
-- Support nested object display
-
-**Draft Mode**:
-
-- Save incomplete forms
-- Skip required field validation
-- Preserve user input
-- Enable resume functionality
-
-### 5. Integration Capabilities
-
-**MUST support:**
-
-- CDN via iframe embedding
-- NPM package installation
-- Direct HTML integration
-- Schema loading via URL parameters
-- Form data prefilling
-- Event-based communication
-
-```html
-<!-- CDN Integration -->
-<iframe
-  src="https://picazru.github.io/form-builder/dist/index.html"
-  width="100%"
-  height="600px"
-></iframe>
-```
-
-### 6. Styling System
-
-**MUST use Tailwind CSS** for all styling:
-
-- Consistent design system
-- Responsive layouts
-- Dark/light theme support
-- Custom CSS property integration
-- Framework compatibility
-
-## Technical Requirements
-
-### 1. Architecture
-
-**Core Stack:**
-
-- HTML5 semantic markup
-- CSS3 with custom properties
-- Vanilla JavaScript (ES6+)
-- Web APIs (FormData, PostMessage, Crypto)
-
-**Performance:**
-
-- Library size <500KB uncompressed
-- Form rendering <2s for 1000 fields
-- Real-time validation without UI blocking
-
-### 2. Browser Support
-
-**MUST support:**
-
-- Chrome 80+, Firefox 75+, Safari 13+, Edge 80+
-- Mobile browsers with touch interfaces
-- Progressive enhancement for older browsers
-
-### 3. Security
-
-**MUST implement:**
-
-- Input sanitization for all user data
-- File type validation (MIME + extension)
-- Secure resource ID generation
-- CSP-compatible code (no inline scripts)
-- Origin validation for iframe communication
-
-### 4. Data Formats
-
-**Schema Format (v0.3):**
-
-```typescript
-interface FormSchema {
-  version: "0.3";
-  title: string;
-  elements: FormElement[];
-}
-```
-
-**Output Format:**
-
-```json
-{
-  "textField": "value",
-  "fileField": "res_abc123",
-  "multipleFiles": ["res_def456", "res_ghi789"],
-  "nestedGroup": {
-    "subField": "value"
-  }
-}
-```
-
-## Quality Requirements
-
-### Performance Metrics
-
-- **Form Rendering**: <2 seconds for 1000 fields
-- **File Upload**: >95% success rate under size limits
-- **Validation Speed**: <100ms per field
-- **Memory Usage**: <50MB for large forms
-
-### Reliability
-
-- **Browser Compatibility**: >99% success rate on target browsers
-- **Error Recovery**: Graceful fallback for all error conditions
-- **Data Integrity**: No data loss during form interactions
-
-### Usability
-
-- **Accessibility**: WCAG 2.1 AA compliance
-- **Mobile Support**: Touch-friendly interfaces
-- **Error Messages**: Clear, actionable feedback
-- **Loading States**: Visual feedback for all operations
-
-## Deployment Requirements
-
-### 1. CDN Distribution
-
-- GitHub Pages hosting for global availability
-- Versioned URLs for stable integration
-- Automatic deployment on releases
-
-### 2. NPM Package
-
-- Published as `@dmitryvim/form-builder`
-- ES6 module support
-- CommonJS compatibility
-- TypeScript definitions
-
-### 3. Versioning
-
-- Semantic versioning (SemVer)
-- Backwards compatibility within major versions
-- Migration guides for breaking changes
-
-## Success Criteria
-
-### Acceptance Criteria
-
-- [ ] All field types render and validate correctly
-- [ ] File uploads work with custom handlers
-- [ ] Read-only mode displays data properly
-- [ ] Draft saving works without validation
-- [ ] Tailwind CSS styling applies correctly
-- [ ] Cross-browser compatibility verified
-- [ ] > 80% test coverage achieved
-- [ ] Performance benchmarks met
-
-### Business Metrics
-
-- **Developer Adoption**: Measurable NPM downloads
-- **Integration Success**: Working implementations in production
-- **Performance Goals**: Sub-2-second form rendering
-- **Error Rates**: <1% form submission failures
-
-## Constraints & Assumptions
-
-### Technical Constraints
-
-- No external dependencies allowed
-- Must work in iframe sandboxes
-- File handling delegated to integrating application
-- Cannot make direct network requests (CORS limitations)
-
-### Business Constraints
-
-- Open source MIT license
-- Community-driven development
-- GitHub-only deployment pipeline
-- No specific backend requirements
-
-### Assumptions
-
-- Integrating applications handle file storage
-- Modern browser environment (ES6+ support)
-- Developers familiar with JSON Schema concepts
-- Basic understanding of iframe communication
-
-## Future Considerations
-
-### Potential Enhancements
-
-- Conditional field logic (show/hide based on values)
-- Custom field type plugins
-- Advanced file processing (image cropping, etc.)
-- Internationalization support
-- Real-time collaboration features
-
-### Not In Scope
-
-- Backend file storage implementation
-- Database integration
-- User authentication/authorization
-- Advanced form analytics
-- Multi-page form wizards
-
-This requirements document defines the core functionality and quality standards for the Form Builder library, ensuring it meets both current needs and provides a foundation for future growth.