# 🎨 Chat Widget Types & Migration System

Professional TypeScript definitions and migration system for HyperShadow Chat Widget configurations with support for version upgrades.

## ⚡ Features

- 🏗️ **Complete TypeScript definitions** for all widget configurations
- 🚀 **Professional migration system** V1 → V2 (and extensible for future versions)
- 🎛️ **CLI tools** for config migration
- 📊 **Detailed migration reports** and logging
- 🛡️ **Safe migrations** with backup and validation
- 🔧 **Extensible architecture** for future versions
- 📈 **High performance** (~200-500 migrations/sec)

## 📦 Installation

```bash
npm install @yartsun/chat-widget-types
```

## 🎯 Quick Usage

```typescript
import { WidgetConfig, quickMigrateV1toV2 } from '@yartsun/chat-widget-types'

// Type-safe configuration
const config: WidgetConfig = {
  settings: { /* ... */ },
  sections: { /* ... */ }
}

// Quick migration V1 → V2
const configV1 = { /* your V1 config */ }
const configV2 = await quickMigrateV1toV2(configV1)
```

## 🎨 Themes (V3 presets)

You can import JSON theme presets directly from the package.

### Import by file path (subpath export)

```typescript
import softTheme from '@yartsun/chat-widget-types/themes/configV3-soft.json'
import shineTheme from '@yartsun/chat-widget-types/themes/configV3-shine.json'
import ultraTheme from '@yartsun/chat-widget-types/themes/configV3-ultra.json'
```

### Import by named alias (THEME_*)

```typescript
import softTheme from '@yartsun/chat-widget-types/THEME_V3_SOFT'
import shineTheme from '@yartsun/chat-widget-types/THEME_V3_SHINE'
import ultraTheme from '@yartsun/chat-widget-types/THEME_V3_ULTRA'
```

## 🔄 Configuration Migration

### Simple Migration

```typescript
import { quickMigrateV1toV2 } from '@yartsun/chat-widget-types'

const migratedConfig = await quickMigrateV1toV2(yourV1Config)
if (migratedConfig) {
  console.log('✅ Migration successful!')
}
```

### Advanced Migration with Reports

```typescript
import { MigrationFacade, MigrationPresets } from '@yartsun/chat-widget-types'

const facade = new MigrationFacade(true) // verbose mode

// Preview migration
const preview = await facade.preview(config, '2.0')
console.log(`Will apply ${preview.appliedStrategies.length} strategies`)

// Execute migration
const result = await facade.migrateV1toV2(config, MigrationPresets.DEBUG)
if (result.success) {
  console.log('Migration completed:', result.appliedStrategies)
}
```

## 🎛️ CLI Migration Tool

```bash
# Simple migration
npm run migrate -- -i examples/configV1.json

# Migration with backup and verbose output
npm run migrate -- -i config.json -o config-v2.json -b -v

# Preview migration without executing
npm run migrate -- -i config.json -p

# Help
npm run migrate:help
```

### Available Scripts

- `npm run migrate` - Run migration CLI
- `npm run migrate:demo` - Full migration demonstration
- `npm run migrate:examples` - Run all examples
- `npm run migrate:help` - Show CLI help

## 📊 What Changed in V2?

### New Settings Fields:
- `loader`: Animation type for loading states
- `buttonStyle`: Button appearance style
- `buttonType`: Button content type

### New Section Features:
- `chipStyle` in top section parameters
- `bgType` for message backgrounds (bubble/plain)
- `aprooveButton` & `rejectButton` for user actions
- Enhanced `inputSend` with border styles and input types
- `warningAlert` component
- `disclaimer` text support

## 🏗️ Architecture

The migration system uses professional design patterns:

- **Strategy Pattern** - Modular migration strategies
- **Command Pattern** - Validation and utility commands  
- **Facade Pattern** - Simple API interface
- **Factory Pattern** - Strategy and command creation

```
src/migration/
├── types.ts      # Type definitions
├── strategies.ts # Migration strategies V1→V2
├── commands.ts   # Validation & utility commands
├── migrator.ts   # Core migration engine
├── facade.ts     # Simple API facade
└── examples.ts   # Usage examples
```

## 🔧 Core Types

```typescript
// Main configuration
interface WidgetConfig {
  settings: WidgetSettings
  sections: WidgetSections
}

// Settings with V2 enhancements
interface WidgetSettings {
  // Core fields
  widgetTitle: string
  welcomeMessage: string
  bgChat: string
  
  // V2 additions
  loader?: Loader
  buttonStyle?: ButtonStyle
  buttonType?: BtnType
}

// Enhanced sections
interface WidgetSections {
  top: TopSection    // Enhanced with chipStyle
  inside: InsideSection  // Added approve/reject buttons
  bottom: BottomSection  // Added warning alerts
}
```

### Utility Functions

```typescript
import {
  extractSettings,
  buildWidgetConfig,
} from '@yartsun/chat-widget-types'

// Extract structured settings from config
const settings = extractSettings(widgetConfig)

// Build config from separate settings
const newConfig = buildWidgetConfig(general, shapes, colors, fonts)
```

## 🎯 Extending for New Versions

The system is designed for easy extension. To add V3:

1. **Update types**:
```typescript
export type ConfigVersion = '1.0' | '2.0' | '3.0'
export interface ConfigV3 extends ConfigV2 { /* new fields */ }
```

2. **Create strategies**:
```typescript
export class AddNewFeatureV2toV3Strategy extends BaseMigrationStrategy {
  name = 'AddNewFeatureV2toV3'
  appliesTo = { from: '2.0', to: '3.0' }
  // implementation
}
```

3. **Register strategies**:
```typescript
export const V2_TO_V3_STRATEGIES = [new AddNewFeatureV2toV3Strategy()]
```

## 🧪 Examples & Demo

Run the full demonstration:

```bash
npm run migrate:demo
```

This includes:
- Real file migration (examples/configV1.json → V2)
- Performance testing (100 migrations)
- All migration modes demonstration
- Comparison with reference V2 config

## 📈 Performance

- **Speed**: ~2-5ms per migration
- **Throughput**: ~200-500 migrations/second
- **Memory**: Minimal footprint
- **Reliability**: 100% success rate on valid V1 configs

## 🛡️ Safety Features

- ✅ **Automatic version detection**
- ✅ **Input validation**
- ✅ **Backup creation** before migration
- ✅ **Rollback support** (where applicable)
- ✅ **Detailed error reporting**
- ✅ **Dry-run mode** for previewing changes

## 📚 API Reference

### Quick Functions
- `quickMigrateV1toV2(config)` - Simple V1→V2 migration
- `quickMigrateToLatest(config)` - Migrate to latest version

### Classes
- `MigrationFacade` - Main API interface
- `ConfigMigrator` - Core migration engine
- `ConfigHelpers` - Utility functions

### Presets
- `MigrationPresets.STRICT` - Fail on any error
- `MigrationPresets.SOFT` - Continue on errors
- `MigrationPresets.DEBUG` - Verbose logging
- `MigrationPresets.PRODUCTION` - Minimal output

## 🔧 Development

### Building

```bash
npm run build
```

### Testing Migration

```bash
# Run all examples
npm run migrate:examples

# Full demo with performance tests
npm run migrate:demo

# Test specific migration
npm run migrate -- -i examples/configV1.json -p
```

## 🤝 Contributing

1. Follow TypeScript best practices
2. Extend `BaseMigrationStrategy` for new strategies
3. Add comprehensive tests
4. Update documentation
5. Follow SOLID principles

## 📄 License

MIT License - Free for commercial and non-commercial use.

## 🔗 Links

- [GitHub Repository](https://github.com/yartsun/chat-widget-types)
- [NPM Package](https://www.npmjs.com/package/@yartsun/chat-widget-types)
- [Migration System Documentation](./migrator/README.md)

---

**Built with ❤️ for professional widget configuration management**