Package Exports

@alchemyui/chat
@alchemyui/chat/dist/alchemy.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@alchemyui/chat) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

AlchemyJS

A modern, lightweight chat UI library for web applications.

Quickstart

Using CDN

<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

# Install the package
npm install alchemyjs

# Import in your code
import { AlchemyChat } from 'alchemyjs';

# Initialize chat
const chat = new AlchemyChat('#chat-container');

Framework Examples

# 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:

{
    "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:

npm run cast-spells
# The enchanted library will appear in dist/alchemy.js

Common enchantments:

# 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:

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

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

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

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

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

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

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

{
    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:

// webpack.config.js
module.exports = {
    entry: './src/alchemy.js',
    output: {
        filename: 'alchemy.js',
        library: 'AlchemyChat',
        libraryTarget: 'umd'
    },
    // ... other webpack configuration
};

Common build commands:

# 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

# 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

Theme Synchronization Ritual

// Bind your chat to the system's natural cycles
const chat = new AlchemyChat('#portal', {
  interface: { preferSystemTheme: true }
});

Message Persistence Charm

// Store messages in the eternal void
const chat = new AlchemyChat('#portal', {
  storage: {
    type: 'local',
    key: 'eternal_messages'
  }
});

Scroll Enchantment

// Smooth scrolling like a floating feather
const chat = new AlchemyChat('#portal', {
  behavior: {
    scrollBehavior: 'smooth',
    autoScroll: true
  }
});

🎨 Style Transmutation

Dark Arts Toggle

/* Add mystical transitions */
.alchemy-chat {
  transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}

Message Bubble Enchantment

// Create ethereal message bubbles
const chat = new AlchemyChat('#portal', {
  theme: {
    sizing: {
      messageBorderRadius: '20px 20px 3px 20px'
    }
  }
});

📜 Ancient Scrolls (Pro Tips)

The Rule of Conservation
- Always cast your spells (npm run cast-spells) before deploying
- Keep your enchantments modular and reusable
- Document your magical discoveries
The Principle of Harmony
- Let your chat flow naturally with system themes
- Maintain consistent spacing in your layouts
- Use smooth transitions for magical effects
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

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

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

Browser Support

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.