# Form Flow - Type-Safe Form System

A declarative, type-safe form definition system for Vue 3.

## Features

✅ **Full TypeScript type safety** - Schema keys must match your interface  
✅ **Field type validation** - `$.number()` for numbers, `$.text()` for strings  
✅ **Nested objects** - Dot notation support: `'meta.preferences.theme'`  
✅ **Array fields** - With `$.array()`  
✅ **Conditional rendering** - SCIM queries: `.if('age gt 13')`  
✅ **Custom validation** - Chain `.validate()` methods  
✅ **Custom components** - `$.component(MyComponent, props)`  
✅ **Slot composition** - `.slot(Component)` for wrapping/customization  
✅ **Auto-generated labels** - From field names  
✅ **Chainable API** - `.row()`, `.if()`, `.validate()`, `.slot()`  
✅ **JSONSchema export** - `schema.toJSONSchema()`  

## Quick Start

```typescript
import { $, schema, required } from './form-flow'
import FormFlow from './FormFlow.vue'

interface User {
  email: string
  firstName: string
  lastName: string
  age: number
  newsletter?: boolean
}

const userSchema = schema<User>({
  email: $.email({ required }),  // syntactic sugar for required: true
  firstName: $.text({ required }).row(),
  lastName: $.text({ required }).row(),
  age: $.number({ min: 18, required }),
  newsletter: $.checkbox().if('age gt 13')
})
```

```vue
<template>
  <FormFlow v-model="userData" :schema="userSchema" />
</template>
```

## Files

- `form-flow.ts` - Core schema builder (`$`, `schema`, `multiStepSchema`)
- `FormFlow.vue` - Single-step form renderer with validation
- `MultiStepForm.vue` - Multi-step form renderer with navigation
- `example.ts` - Comprehensive API examples
- `demo.vue` - Simple working demo
- `demo-enhanced.vue` - Full-featured demo with all capabilities

## Field Types

- **Text**: `$.text()`, `$.email()`, `$.password()`, `$.tel()`, `$.url()`
- **Numbers**: `$.number({ min, max, step })`
- **Dates**: `$.date({ min, max })`, `$.time()`, `$.datetime()`
- **Text areas**: `$.textarea()`, `$.richtext()`
- **Selections**: `$.select()`, `$.multiselect()`, `$.radio()`
- **Boolean**: `$.checkbox()`, `$.toggle()`
- **Arrays**: `$.array(label, schema?, options)`
- **Custom**: `$.component(Component, props)`

## Chainable Methods

```typescript
import { required } from './form-flow'

$.email({ required })       // Use 'required' shorthand
  .row()                    // Side-by-side layout
  .if('age gt 18')          // Conditional visibility
  .validate(v => ...)       // Custom validation
  .slot(Card, { title })    // Wrap in component
```

## Syntactic Sugar

**`required` shorthand:**
```typescript
import { required } from './form-flow'

// These are equivalent:
$.email({ required })
$.email({ required: true })

// Clean and concise:
const schema = schema<User>({
  email: $.email({ required }),
  name: $.text({ required, placeholder: 'Enter name' }),
  age: $.number({ min: 18, required })
})
```

## Advanced Features

### Validation
```typescript
email: $.email({ required: true })
  .validate(v => v.includes('@') || 'Invalid email')
  .validate(v => v.length > 5 || 'Too short')
```

### Custom Components
```typescript
birthDate: $.component(DatePicker, {
  format: 'YYYY-MM-DD',
  minDate: '1900-01-01'
})
```

### Multi-Step Forms
```typescript
const flow = multiStepSchema<T>({
  step1: schema('Step 1', { /* fields */ }),
  step2: schema('Step 2', { /* fields */ }).if('condition')
})
```

```vue
<MultiStepForm 
  v-model="data" 
  :schema="flow"
  @complete="handleComplete"
/>
```

### Nested Objects
```typescript
schema<User>({
  'meta.bio': $.text(),
  'meta.preferences.theme': $.select(['light', 'dark'])
})
```

### Custom Field Rendering
```vue
<FormFlow v-model="data" :schema="schema">
  <template #field:email="{ value, onChange, field }">
    <MyCustomInput :value="value" @update="onChange" />
  </template>
</FormFlow>
```

## What's Implemented

✅ **Core Schema System** (`form-flow.ts`)
- All field types with full configuration
- Chainable API (`.if()`, `.validate()`, `.row()`, `.slot()`)
- Type inference and safety
- JSONSchema export

✅ **FormFlow Component**
- Automatic field rendering
- SCIM condition evaluation
- Nested object support (dot notation)
- Validation with error display
- Custom component rendering
- Template slot overrides
- Auto-generated labels

✅ **MultiStepForm Component**
- Step navigation (prev/next)
- Progress indicator
- Conditional steps
- Data persistence across steps
- Complete event handling

✅ **Examples & Demos**
- Comprehensive API examples (`example.ts`)
- Simple demo (`demo.vue`)
- Full-featured demo (`demo-enhanced.vue`)

## Next Steps

1. Add more field types (FileUpload, ColorPicker, RichTextEditor)
2. Implement `.slot()` wrapper rendering (AST-style composition)
3. Add async validation support
4. Connect to DataTable for column definitions
5. Connect to Filter for field configuration
6. Add form submission handling
7. Add field dependencies (computed fields)