🎨 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

npm install @yartsun/chat-widget-types

🎯 Quick Usage

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)

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_*)

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

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

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

Advanced Migration with Reports

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

# 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

// 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

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:

export type ConfigVersion = '1.0' | '2.0' | '3.0'
export interface ConfigV3 extends ConfigV2 { /* new fields */ }

2. Create strategies:

export class AddNewFeatureV2toV3Strategy extends BaseMigrationStrategy {
  name = 'AddNewFeatureV2toV3'
  appliesTo = { from: '2.0', to: '3.0' }
  // implementation
}

3. Register strategies:

export const V2_TO_V3_STRATEGIES = [new AddNewFeatureV2toV3Strategy()]

🧪 Examples & Demo

Run the full demonstration:

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

npm run build

Testing Migration

# 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
• NPM Package
• Migration System Documentation

Built with ❤️ for professional widget configuration management