@swimdubs/chat NPM

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)
  }
});