@tachui/forms 0.7.1-alpha → 0.8.1-alpha

package/README.md

@@ -1,321 +1,136 @@
 # @tachui/forms
 
-> Advanced form components and validation system for tachUI framework
+Comprehensive form components and validation system for tachUI - unified package combining all form functionality.
 
-[![npm version](https://img.shields.io/npm/v/@tachui/forms.svg)](https://www.npmjs.com/package/@tachui/forms)
-[![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](https://opensource.org/licenses/MPL-2.0)
+## What's New in v2.0
 
-## Overview
-
-The tachUI forms package provides advanced form components, validation utilities, and form state management that extends the core tachUI framework with powerful form-building capabilities.
-
-## Features
-
-- 🎯 **Advanced Form Components** - TextField, Select, Checkbox, Radio, and more
-- ✅ **Built-in Validation** - Schema-based validation with real-time feedback
-- 🔄 **Reactive Form State** - Automatic state management and synchronization
-- 🎨 **SwiftUI-style API** - Familiar component patterns and modifiers
-- 📱 **Mobile-friendly** - Touch-optimized inputs and interactions
-- 🔧 **TypeScript-first** - Complete type safety for forms and validation
+- **Unified Package**: All 27 form components in one optimized package
+- **20% Bundle Reduction**: From 488KB to ~390KB through build optimization
+- **Tree Shaking**: Import only the components you need
+- **Backwards Compatible**: Maintains all existing APIs
 
 ## Installation
 
 ```bash
-npm install @tachui/core @tachui/forms
-# or
-pnpm add @tachui/core @tachui/forms
+pnpm add @tachui/forms
 ```
 
 ## Quick Start
 
 ```typescript
-import { VStack, Button } from '@tachui/core'
-import { Form, TextField, Select, createFormState } from '@tachui/forms'
-
-// Create form state
-const formState = createFormState(
-  {
-    name: '',
-    email: '',
-    country: 'US',
-  },
-  {
-    name: { required: true, minLength: 2 },
-    email: { required: true, email: true },
-    country: { required: true },
-  }
-)
-
-const contactForm = Form({
-  state: formState,
-  children: [
-    VStack({
-      children: [
-        TextField('Name', formState.binding('name'))
-          .modifier.placeholder('Enter your name')
-          .build(),
-
-        TextField('Email', formState.binding('email'))
-          .modifier.placeholder('Enter your email')
-          .keyboardType('email')
-          .build(),
-
-        Select(
-          'Country',
-          [
-            { value: 'US', label: 'United States' },
-            { value: 'CA', label: 'Canada' },
-            { value: 'UK', label: 'United Kingdom' },
-          ],
-          formState.binding('country')
-        ).build(),
-
-        Button('Submit', () => {
-          if (formState.validate()) {
-            console.log('Form data:', formState.values())
-          }
-        })
-          .modifier.disabled(() => !formState.isValid())
-          .build(),
-      ],
-      spacing: 16,
-    }).build(),
-  ],
-}).build()
-```
+import { Form, TextField, DatePicker, validation } from '@tachui/forms'
 
-## Components
+// Or use granular imports for optimal bundle size
+import { TextField } from '@tachui/forms/text-input'
+import { DatePicker } from '@tachui/forms/date-picker'
+import { required, email } from '@tachui/forms/validation'
+```
 
-### TextField
+## Components (27 total)
 
-Advanced text input with validation and formatting:
+### Form Container (2 components)
 
-```typescript
-import { TextField } from '@tachui/forms'
-
-TextField('Password', passwordBinding)
-  .modifier.placeholder('Enter password')
-  .secureTextEntry(true)
-  .minLength(8)
-  .validation(value => (value.length >= 8 ? null : 'Password too short'))
-  .build()
-```
+- `Form` - Form state management and submission
+- `FormSection` - Logical grouping of form fields
 
-### Select & Picker
+### Text Input (14 components)
 
-Dropdown selections with search and multi-select:
+- `TextField` - Basic text input
+- `TextArea` - Multi-line text input
+- `EmailField` - Email validation and formatting
+- `PasswordField` - Password input with visibility toggle
+- `SearchField` - Search input with clear button
+- `URLField` - URL validation and formatting
+- `PhoneField` - Phone number formatting and validation
+- `NumberField` - Numeric input with validation
+- `CreditCardField` - Credit card formatting and validation
+- `SSNField` - Social Security Number formatting
+- `PostalCodeField` - Postal/ZIP code validation
+- `DateField` - Simple date text input
+- `TimeField` - Time input and validation
+- `ColorField` - Color picker input
 
-```typescript
-import { Select, Picker } from '@tachui/forms'
+### Selection (8 components)
 
-Select('Category', categories, selectedCategory)
-  .modifier.searchable(true)
-  .placeholder('Choose category')
-  .build()
+- `Checkbox` - Single checkbox input
+- `CheckboxGroup` - Multiple checkbox group
+- `Switch` - Toggle switch input
+- `Radio` - Single radio button
+- `RadioGroup` - Radio button group
+- `Select` - Single select dropdown
+- `MultiSelect` - Multiple selection dropdown
+- `Combobox` - Searchable select input
 
-Picker('Colors', colors, selectedColors)
-  .modifier.multiSelect(true)
-  .displayStyle('compact')
-  .build()
-```
+### Advanced (3 components)
 
-### Checkbox & Radio
+- `DatePicker` - Rich calendar interface
+- `Stepper` - Numeric increment/decrement
+- `Slider` - Range input with marks
 
-Selection controls with grouping:
+## Tree-Shaking Examples
 
 ```typescript
-import { Checkbox, RadioGroup } from '@tachui/forms'
+// Import entire package (390KB)
+import { TextField, DatePicker, validation } from '@tachui/forms'
 
-Checkbox('Accept Terms', acceptedBinding).modifier.required(true).build()
+// Import specific categories (~180KB for text inputs)
+import * as TextInputs from '@tachui/forms/text-input'
+import * as Validation from '@tachui/forms/validation'
 
-RadioGroup('Size', sizeOptions, selectedSize)
-  .modifier.layout('horizontal')
-  .build()
+// Import individual components (~20-30KB each)
+import { TextField } from '@tachui/forms/text-input'
+import { required, email } from '@tachui/forms/validation'
 ```
 
-## Form State Management
+## Migration from v1.x
 
-### Creating Form State
+### From @tachui/forms + @tachui/advanced-forms
 
 ```typescript
-import { createFormState } from '@tachui/forms'
-
-const userForm = createFormState(
-  {
-    firstName: '',
-    lastName: '',
-    age: 0,
-    preferences: [],
-  },
-  {
-    // Validation rules
-    firstName: {
-      required: true,
-      minLength: 2,
-      pattern: /^[A-Za-z]+$/,
-    },
-    lastName: {
-      required: true,
-      minLength: 2,
-    },
-    age: {
-      required: true,
-      min: 18,
-      max: 120,
-    },
-  }
-)
-```
+// Old approach (488KB total)
+import { TextField, Form } from '@tachui/forms'
+import { DatePicker, Stepper } from '@tachui/advanced-forms'
 
-### Form Bindings
+// New unified approach (390KB total)
+import { TextField, Form, DatePicker, Stepper } from '@tachui/forms'
 
-```typescript
-// Two-way data binding
-const nameBinding = userForm.binding('firstName')
-
-// Custom validation
-const emailBinding = userForm.binding('email', {
-  validator: value => {
-    if (!value.includes('@')) return 'Invalid email'
-    return null
-  },
-  debounce: 300,
-})
+// Or with tree-shaking (as needed)
+import { TextField, Form } from '@tachui/forms/text-input'
+import { DatePicker } from '@tachui/forms/date-picker'
+import { Stepper } from '@tachui/forms/advanced'
 ```
 
-### Form Validation
+### Backwards Compatibility
 
-```typescript
-// Validate entire form
-const isValid = userForm.validate()
-
-// Check specific field
-const hasErrors = userForm.hasErrors('firstName')
-
-// Get validation errors
-const errors = userForm.getErrors()
-
-// Real-time validation status
-createEffect(() => {
-  if (userForm.isValid()) {
-    console.log('Form is valid!')
-  }
-})
-```
+All existing APIs remain unchanged. Migration is optional and can be done incrementally.
 
-## Advanced Features
+## Validation System
 
-### Custom Validation
+Comprehensive validation with 20+ built-in rules:
 
 ```typescript
-import { createValidator } from '@tachui/forms'
-
-const passwordValidator = createValidator({
-  minLength: 8,
-  requireUppercase: true,
-  requireLowercase: true,
-  requireNumbers: true,
-  requireSymbols: true,
-})
-
-TextField('Password', passwordBinding)
-  .modifier.validator(passwordValidator)
-  .build()
-```
+import { validation } from '@tachui/forms'
 
-### Form Schemas
-
-```typescript
-import { createFormSchema } from '@tachui/forms'
-
-const registrationSchema = createFormSchema({
-  username: {
-    type: 'string',
-    required: true,
-    minLength: 3,
-    maxLength: 20,
-    pattern: /^[a-zA-Z0-9_]+$/,
-  },
-  email: {
-    type: 'email',
-    required: true,
-  },
-  birthDate: {
-    type: 'date',
-    required: true,
-    maxDate: new Date(),
-  },
+const schema = validation.object({
+  email: validation.string().email().required(),
+  password: validation.string().min(8).required(),
+  confirmPassword: validation.string().matches('password'),
+  age: validation.number().min(18).max(120),
 })
-
-const form = createFormState({}, registrationSchema)
-```
-
-### Conditional Fields
-
-```typescript
-const surveyForm = createFormState({
-  hasExperience: false,
-  yearsExperience: 0,
-})
-
-// Show years field only if has experience
-Show(
-  () => surveyForm.values().hasExperience,
-  () =>
-    TextField('Years of Experience', surveyForm.binding('yearsExperience'))
-      .modifier.keyboardType('numeric')
-      .build()
-).build()
-```
-
-## Styling and Theming
-
-Forms inherit tachUI's modifier system:
-
-```typescript
-TextField('Email', emailBinding)
-  .modifier.padding(16)
-  .backgroundColor('#f8f9fa')
-  .cornerRadius(8)
-  .border({ width: 1, color: '#dee2e6' })
-  .focusBorderColor('#007AFF')
-  .errorBorderColor('#dc3545')
-  .build()
 ```
 
-## Accessibility
-
-Built-in accessibility features:
-
-- **ARIA labels** and descriptions
-- **Keyboard navigation** support
-- **Screen reader** compatibility
-- **Focus management** and indicators
-- **Error announcements** for validation
-
-## Examples
-
-Check out complete examples:
-
-- **[Contact Form](https://github.com/tach-UI/tachUI/tree/main/apps/examples/forms/contact)**
-- **[Registration Form](https://github.com/tach-UI/tachUI/tree/main/apps/examples/forms/registration)**
-- **[Survey Builder](https://github.com/tach-UI/tachUI/tree/main/apps/examples/forms/survey)**
-
-## API Reference
-
-- **[TextField API](https://github.com/tach-UI/tachUI/blob/main/docs/api/forms/src/classes/TextField.md)**
-- **[Form State API](https://github.com/tach-UI/tachUI/blob/main/docs/api/forms/src/functions/createFormState.md)**
-- **[Validation API](https://github.com/tach-UI/tachUI/blob/main/docs/api/forms/src/functions/createValidator.md)**
-
-## Requirements
-
-- **@tachui/core** ^0.7.0-alpha1 or later
-- **TypeScript** 5.0+ (recommended)
-
-## Contributing
+## Bundle Size Comparison
 
-See the main [Contributing Guide](https://github.com/tach-UI/tachUI/blob/main/CONTRIBUTING.md) for information on contributing to tachUI forms.
+| Package        | v1.x (Split)   | v2.0 (Unified) | Savings   |
+| -------------- | -------------- | -------------- | --------- |
+| Text Inputs    | 149KB          | 120KB          | 19%       |
+| Advanced Forms | 268KB          | 80KB           | 70%       |
+| Date Picker    | Included above | 60KB           | Optimized |
+| **Total**      | **488KB**      | **390KB**      | **20%**   |
 
-## License
+## Documentation
 
-Mozilla Public License 2.0 - see [LICENSE](https://github.com/tach-UI/tachUI/blob/main/LICENSE) for details.
+- [Component API Reference](./docs/components.md)
+- [Validation Guide](./docs/validation.md)
+- [Migration Guide](./docs/migration.md)
+- [Bundle Optimization](./docs/optimization.md)