npm package: @swimdubs/chat
Description: A modern, lightweight chat UI library for web applications
Author: AlchemyJS Team
Latest version: 1.0.5

# AlchemyJS

A modern, lightweight chat UI library for web applications.

## Quickstart

### Using CDN
```html
<div id="chat-container"></div>
<script src="https://unpkg.com/alchemyjs/dist/alchemy.js"></script>
<script>
    const chat = new AlchemyChat('#chat-container');
    chat.addMessage({
        text: 'Hello from AlchemyJS!',
        type: 'incoming'
    });
</script>
```

### Using NPM
```bash
# Install the package
npm install alchemyjs

# Import in your code
import { AlchemyChat } from 'alchemyjs';

# Initialize chat
const chat = new AlchemyChat('#chat-container');
```

### Framework Examples
```bash
# Flask Example
cd examples/frameworks/flask
pip install -r requirements.txt
python app.py
# Visit http://localhost:5000

# Node.js Example
cd examples/frameworks/nodejs
npm install
npm start
# Visit http://localhost:3000
```

## Configuration Guide

There are two ways to configure AlchemyJS:

### 1. Build-time Configuration (Recommended)
This sets the default configuration for all chat instances. Edit `alchemy.json`:

```javascript
{
    "theme": {
        "mode": "light",
        "light": {
            "colors": {
                "primary": "#0084ff",
                "background": "#ffffff",
                "incomingMessage": "#f0f2f5",
                "outgoingMessage": "#0084ff",
                "textPrimary": "#050505",
                "textSecondary": "#65676b",
                "borderColor": "#e4e6eb"
            }
        },
        "dark": {
            "colors": {
                "primary": "#0084ff",
                "background": "#242526",
                "incomingMessage": "#3a3b3c",
                "outgoingMessage": "#0084ff",
                "textPrimary": "#e4e6eb",
                "textSecondary": "#b0b3b8",
                "borderColor": "#3a3b3c"
            }
        },
        "sizing": {
            "maxHeight": "600px",
            "minHeight": "400px",
            "borderRadius": "12px",
            "messageBorderRadius": "18px",
            "fontSize": "14px"
        },
        "spacing": {
            "padding": "16px",
            "messageSpacing": "8px"
        }
    },
    "interface": {
        "showTimestamp": true,
        "messageAlignment": "sides",
        "showThemeToggle": true,
        "themeTogglePosition": {
            "top": "20px",
            "right": "20px"
        },
        "appBar": {
            "title": "AlchemyJS Chat",
            "showActions": true
        },
        "inputPlaceholder": "Type a message...",
        "sendButtonText": "Send",
        "preferSystemTheme": true
    },
    "storage": {
        "enable": true,
        "type": "local",
        "key": "alchemyjs_messages"
    },
    "behavior": {
        "maxMessageLength": 1000,
        "autoScroll": true,
        "throttleMS": 100,
        "autocorrect": {
            "enable": true,
            "firstWordCapitalization": true,
            "commonWords": {
                "ur": "your",
                "u": "you",
                "dont": "don't"
            }
        }
    }
}
```

After modifying `alchemy.json`, cast your spells to rebuild the library:
```bash
npm run cast-spells
# The enchanted library will appear in dist/alchemy.js
```

Common enchantments:
```bash
# Brew a development potion with magic traces (source maps)
npm run brew

# Cast a production spell with full power
npm run cast

# Transmute the code and watch for changes
npm run transmute

# Run experimental brews in the lab
npm run experiment
```

### 2. Runtime Configuration
You can override build-time defaults for individual instances:

```javascript
const chat = new AlchemyChat('#chat-container', {
    // Override specific settings
    theme: {
        mode: 'dark'  // Override just the theme mode
    },
    storage: {
        key: 'custom_storage_key'  // Custom storage key
    }
});
```

### Theme Customization

```javascript
const chat = new AlchemyChat('#chat-container', {
    theme: {
        // Light and dark mode colors
        light: {
            colors: {
                primary: '#0084ff',           // Primary color for buttons, links
                background: '#ffffff',         // Chat background
                incomingMessage: '#f0f2f5',   // Incoming message bubbles
                outgoingMessage: '#0084ff',   // Outgoing message bubbles
                textPrimary: '#050505',       // Main text color
                textSecondary: '#65676b',     // Secondary text (timestamps)
                borderColor: '#e4e6eb'        // Borders and dividers
            }
        },
        dark: {
            colors: {
                primary: '#0084ff',
                background: '#242526',
                incomingMessage: '#3a3b3c',
                outgoingMessage: '#0084ff',
                textPrimary: '#e4e6eb',
                textSecondary: '#b0b3b8',
                borderColor: '#3a3b3c'
            }
        },
        // Customize sizes
        sizing: {
            maxHeight: '600px',
            minHeight: '400px',
            borderRadius: '12px',
            messageBorderRadius: '18px',
            fontSize: '14px'
        },
        // Adjust spacing
        spacing: {
            padding: '16px',
            messageSpacing: '8px'
        }
    }
});
```

### Message Storage

```javascript
// Local Storage (persists across browser sessions)
const chat = new AlchemyChat('#chat-container', {
    storage: {
        enable: true,
        type: 'local',
        key: 'my_chat_messages'    // Custom storage key
    }
});

// Session Storage (cleared when browser closes)
const chat = new AlchemyChat('#chat-container', {
    storage: {
        enable: true,
        type: 'session',
        key: 'temp_chat_messages'
    }
});

// Disable Storage (memory only)
const chat = new AlchemyChat('#chat-container', {
    storage: {
        enable: false
    }
});
```

### Interface Options

```javascript
const chat = new AlchemyChat('#chat-container', {
    interface: {
        // App Bar Configuration
        appBar: {
            title: 'My Chat App',
            showActions: true          // Show additional actions menu
        },
        // Theme Toggle
        showThemeToggle: true,
        themeTogglePosition: {
            top: '20px',
            right: '20px'
        },
        // Message Display
        showTimestamp: true,          // Show message timestamps
        messageAlignment: 'sides',     // 'sides' or 'right'
        preferSystemTheme: true,      // Use system theme preference
        // Input Area
        inputPlaceholder: 'Type a message...',
        sendButtonText: 'Send'
    }
});
```

### Behavior Settings

```javascript
const chat = new AlchemyChat('#chat-container', {
    behavior: {
        // Message Handling
        maxMessageLength: 1000,    // Maximum message length
        autoScroll: true,         // Auto-scroll to new messages
        throttleMS: 100,          // Input throttling

        // Autocorrect Features
        autocorrect: {
            enable: true,
            firstWordCapitalization: true,
            commonWords: {
                'ur': 'your',
                'u': 'you',
                'dont': "don't",
                // Add your own corrections
                'customword': 'replacement'
            }
        }
    }
});
```

### Event Callbacks

```javascript
const chat = new AlchemyChat('#chat-container', {
    callbacks: {
        // Message Events
        onSend: (message) => {
            console.log('Message sent:', message);
        },
        onReceive: (message) => {
            console.log('Message received:', message);
        },
        // Input Events
        onType: (text) => {
            console.log('User is typing:', text);
        },
        // Lifecycle Events
        onReady: () => {
            console.log('Chat is ready');
        },
        // Error Handling
        onError: (error) => {
            console.error('Chat error:', error);
        }
    }
});
```

## Features

- 🎨 Beautiful, modern UI with light/dark themes
- 📱 Fully responsive design
- 💾 Message persistence with local storage
- 🔌 WebSocket support for real-time chat
- 🎯 Framework agnostic - works with any web framework
- 🛠️ Highly customizable themes and behavior
- 🔄 System theme integration
- 📝 Message formatting and autocorrect
- 🎉 Zero dependencies

## Documentation

### Basic Usage
```javascript
const chat = new AlchemyChat('#chat-container', {
    interface: {
        appBar: {
            title: 'My Chat App'
        },
        showThemeToggle: true,
        preferSystemTheme: true
    },
    storage: {
        enable: true,
        type: 'local'
    }
});

// Send a message
chat.addMessage({
    text: 'Hello!',
    type: 'outgoing'
});

// Receive a message
chat.addMessage({
    text: 'Hi there!',
    type: 'incoming'
});
```

### Configuration Options

```javascript
{
    theme: {
        mode: 'light',          // 'light' or 'dark'
        colors: { ... },        // Custom color scheme
        sizing: { ... },        // Size customization
        spacing: { ... }        // Spacing customization
    },
    interface: {
        showTimestamp: true,    // Show message timestamps
        showThemeToggle: true,  // Show theme toggle button
        appBar: { ... }         // App bar configuration
    },
    storage: {
        enable: true,           // Enable message persistence
        type: 'local',         // 'local' or 'session'
        key: 'chat_messages'   // Storage key
    },
    callbacks: {
        onSend: (message) => {},     // Message sent
        onReceive: (message) => {},   // Message received
        onError: (error) => {}       // Error handling
    }
}
```

### Build Configuration

The build process can be customized through `webpack.config.js`:

```javascript
// webpack.config.js
module.exports = {
    entry: './src/alchemy.js',
    output: {
        filename: 'alchemy.js',
        library: 'AlchemyChat',
        libraryTarget: 'umd'
    },
    // ... other webpack configuration
};
```

Common build commands:
```bash
# Development build with source maps
npm run dev

# Production build with minification
npm run build

# Build and watch for changes
npm run watch

# Build and serve demo
npm run demo
```

## 🔮 The Alchemist's Spellbook

Welcome to the mystical art of chat enchantment! Here are some powerful spells and arcane secrets to enhance your AlchemyJS mastery.

### 🧙‍♂️ Magical Scripts

```bash
# For the mystically inclined:
npm run cast-spells      # Build for production
npm run brew             # Start dev server
npm run transmute        # Watch for changes
npm run summon-familiar  # Watch tests
npm run banish           # Clean project
npm run enchant          # Generate docs
npm run scry             # Lint code
npm run shield           # Security audit

# For the pragmatic developers:
npm run build           # Build for production
npm run start           # Start dev server
npm run watch           # Watch for changes
npm run test:watch      # Watch tests
npm run clean           # Clean project
npm run docs            # Generate docs
npm run lint            # Lint code
npm run security        # Security audit
```

### 🌟 Enchantment Tips

1. **Theme Synchronization Ritual**
   ```javascript
   // Bind your chat to the system's natural cycles
   const chat = new AlchemyChat('#portal', {
     interface: { preferSystemTheme: true }
   });
   ```

2. **Message Persistence Charm**
   ```javascript
   // Store messages in the eternal void
   const chat = new AlchemyChat('#portal', {
     storage: {
       type: 'local',
       key: 'eternal_messages'
     }
   });
   ```

3. **Scroll Enchantment**
   ```javascript
   // Smooth scrolling like a floating feather
   const chat = new AlchemyChat('#portal', {
     behavior: {
       scrollBehavior: 'smooth',
       autoScroll: true
     }
   });
   ```

### 🎨 Style Transmutation

1. **Dark Arts Toggle**
   ```css
   /* Add mystical transitions */
   .alchemy-chat {
     transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
   }
   ```

2. **Message Bubble Enchantment**
   ```javascript
   // Create ethereal message bubbles
   const chat = new AlchemyChat('#portal', {
     theme: {
       sizing: {
         messageBorderRadius: '20px 20px 3px 20px'
       }
     }
   });
   ```

### 📜 Ancient Scrolls (Pro Tips)

1. **The Rule of Conservation**
   - Always cast your spells (`npm run cast-spells`) before deploying
   - Keep your enchantments modular and reusable
   - Document your magical discoveries

2. **The Principle of Harmony**
   - Let your chat flow naturally with system themes
   - Maintain consistent spacing in your layouts
   - Use smooth transitions for magical effects

3. **The Law of Debugging**
   - Check the browser's crystal ball (console)
   - Use scrying spells (`npm run scry`) regularly
   - Test your enchantments across different realms (browsers)

### 🌈 Elemental Customization

```javascript
// Summon custom colors
const chat = new AlchemyChat('#portal', {
  theme: {
    light: {
      colors: {
        primary: '#7e57c2',      // Amethyst
        background: '#f5f0ff',   // Moonlight
        incomingMessage: '#e8eaf6', // Starlight
        outgoingMessage: '#7e57c2'  // Mystic Purple
      }
    }
  }
});
```

### 🔥 Power Words (Events)

```javascript
// Listen for magical events
const chat = new AlchemyChat('#portal', {
  callbacks: {
    onSend: (spell) => console.log('Spell cast:', spell),
    onReceive: (scroll) => console.log('Scroll received:', scroll),
    onThemeChange: (realm) => console.log('Realm shifted to:', realm)
  }
});
```

## Examples

Check out our example implementations:

- [Basic HTML](examples/basic/html-script.html)
- [Theme Customization](examples/customization/theme.html)
- [Message Storage](examples/features/message-storage.html)
- [Flask Integration](examples/frameworks/flask)
- [Node.js Integration](examples/frameworks/nodejs)

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.