npm - @a.izzuddin/ai-chat - Versions diffs - 0.1.1 - Mend

@a.izzuddin/ai-chat 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,293 @@
+# @a.izzuddin/ai-chat
+A **framework-agnostic** AI chat web component built with Lit and TypeScript. Works seamlessly with React, Vue, Svelte, Angular, and vanilla JavaScript.
+[![npm version](https://img.shields.io/npm/v/@yourusername/ai-chat)](https://www.npmjs.com/package/@yourusername/ai-chat)
+[![npm downloads](https://img.shields.io/npm/dm/@yourusername/ai-chat)](https://www.npmjs.com/package/@yourusername/ai-chat)
+## ✨ Features
+- 🌐 **Framework Agnostic** - Works with any framework or no framework
+- 🎨 **Beautiful UI** - Modern chat interface with light/dark mode
+- ⚡ **Lightweight** - Only ~15KB (gzipped)
+- 🔧 **Fully Customizable** - Configure API endpoint, styling, and behavior
+- 📱 **Responsive** - Mobile-friendly design
+- 🎯 **TypeScript** - Full type safety and IntelliSense
+- ♿ **Accessible** - Semantic HTML and ARIA attributes
+- 🎪 **Event-Driven** - Listen to messages, responses, and errors
+## 📦 Installation
+```bash
+npm install @yourusername/ai-chat
+# or
+yarn add @yourusername/ai-chat
+# or
+pnpm add @yourusername/ai-chat
+```
+## 🚀 Quick Start
+### Vanilla JavaScript / HTML
+```html
+<!DOCTYPE html>
+<html>
+<body>
+  <script type="module">
+    import '@yourusername/ai-chat';
+  </script>
+  <ai-chat
+    api-url="https://your-api.com"
+    session-id="user-123"
+    title="My AI Assistant">
+  </ai-chat>
+</body>
+</html>
+```
+### React
+```tsx
+import '@yourusername/ai-chat';
+function App() {
+  return (
+    <ai-chat
+      api-url={process.env.REACT_APP_API_URL}
+      session-id="user-123"
+      title="AI Assistant"
+    />
+  );
+}
+```
+### Vue
+```vue
+<template>
+  <ai-chat
+    :api-url="apiUrl"
+    session-id="user-123"
+    title="AI Assistant"
+  />
+</template>
+<script setup>
+import '@yourusername/ai-chat';
+const apiUrl = import.meta.env.VITE_API_URL;
+</script>
+```
+### Svelte
+```svelte
+<script>
+  import '@yourusername/ai-chat';
+  export let apiUrl;
+</script>
+<ai-chat
+  api-url={apiUrl}
+  session-id="user-123"
+  title="AI Assistant"
+/>
+```
+### Angular
+```typescript
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+import '@yourusername/ai-chat';
+@Component({
+  selector: 'app-root',
+  template: '<ai-chat api-url="..." session-id="user-123"></ai-chat>',
+  schemas: [CUSTOM_ELEMENTS_SCHEMA]
+})
+export class AppComponent {}
+```
+## 📖 API
+### Attributes
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api-url` | `string` | **required** | Your API endpoint URL |
+| `session-id` | `string` | `"default-session"` | Session identifier for conversation context |
+| `title` | `string` | `"My AI Agent"` | Chat header title |
+| `theme` | `"light" \| "dark"` | `"light"` | UI theme |
+| `initial-messages` | `Message[]` | `[]` | Pre-populate chat with messages |
+### Properties (JavaScript)
+```javascript
+const chat = document.querySelector('ai-chat');
+// Set properties
+chat.apiUrl = 'https://api.example.com';
+chat.sessionId = 'user-123';
+chat.title = 'Support Bot';
+chat.theme = 'dark';
+chat.initialMessages = [
+  { id: '1', role: 'assistant', content: 'Hello! How can I help?' }
+];
+```
+### Events
+```javascript
+const chat = document.querySelector('ai-chat');
+// User sends a message
+chat.addEventListener('message-sent', (event) => {
+  console.log('User message:', event.detail);
+  // event.detail: { id: string, role: 'user', content: string }
+});
+// AI responds
+chat.addEventListener('response-received', (event) => {
+  console.log('AI response:', event.detail);
+  // event.detail: { id: string, role: 'assistant', content: string }
+});
+// Error occurs
+chat.addEventListener('error', (event) => {
+  console.error('Chat error:', event.detail);
+  // event.detail: Error object
+});
+```
+### TypeScript Types
+```typescript
+import type { Message } from '@yourusername/ai-chat';
+interface Message {
+  id: string;
+  role: 'user' | 'assistant';
+  content: string;
+}
+```
+## 🔌 Backend API Requirements
+Your API must implement this endpoint:
+**POST `/ask`**
+Request:
+```json
+{
+  "session_id": "string",
+  "question": "string"
+}
+```
+Response:
+```json
+{
+  "response": "string"
+}
+```
+## 🎨 Theming
+### Built-in Themes
+```html
+<!-- Light mode (default) -->
+<ai-chat theme="light"></ai-chat>
+<!-- Dark mode -->
+<ai-chat theme="dark"></ai-chat>
+```
+### CSS Custom Properties
+Customize colors by overriding CSS variables:
+```css
+ai-chat {
+  --ai-chat-primary: #2563eb;
+  --ai-chat-background: #ffffff;
+  --ai-chat-text: #09090b;
+  /* ... more variables */
+}
+```
+### Shadow DOM
+The component uses Shadow DOM for style encapsulation. To style internal elements, use `::part()`:
+```css
+ai-chat::part(header) {
+  background: linear-gradient(to right, #667eea, #764ba2);
+}
+```
+## 📚 Examples
+Check out the [examples](./examples) directory for complete working examples:
+- [Vanilla JavaScript](./examples/vanilla.html)
+- [React](./examples/react.tsx)
+- [Vue](./examples/vue.vue)
+- [Svelte](./examples/svelte.svelte)
+- [Angular](./examples/angular.component.ts)
+## 🌍 Browser Support
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+- Mobile browsers (iOS Safari 14+, Chrome Android)
+Requires native Web Components support (Custom Elements v1, Shadow DOM v1).
+## 🔄 Migration from React Version
+If you were using the React-only version:
+**Before:**
+```tsx
+import { AIChat } from '@yourusername/ai-chat';
+<AIChat apiUrl="..." />
+```
+**After:**
+```tsx
+import '@yourusername/ai-chat';
+<ai-chat api-url="..." />
+```
+Key differences:
+- Component name is lowercase: `<ai-chat>` instead of `<AIChat>`
+- Attributes use kebab-case: `api-url` instead of `apiUrl`
+- Events instead of callback props
+## 🤝 Contributing
+Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md).
+## 📄 License
+MIT © [Your Name]
+## 🔗 Links
+- [Documentation](https://github.com/yourusername/ai-chat#readme)
+- [Examples](./examples)
+- [Issue Tracker](https://github.com/yourusername/ai-chat/issues)
+- [npm Package](https://www.npmjs.com/package/@yourusername/ai-chat)
+## ⭐ Similar Projects
+- [@n8n/chat](https://www.npmjs.com/package/@n8n/chat) - n8n's chat widget
+- [Lit](https://lit.dev/) - The library powering this component
+---
+**Built with [Lit](https://lit.dev/)** • **Powered by Web Components**

package/README.npm.md ADDED Viewed

@@ -0,0 +1,293 @@
+# @yourusername/ai-chat
+A beautiful, configurable AI chat component for React applications. Built with Radix UI, Tailwind CSS, and TypeScript.
+## Features
+- 🎨 **Beautiful UI** - Modern chat interface with dark mode support
+- ⚡ **Lightweight** - Minimal dependencies, optimized bundle size
+- 🔧 **Configurable** - Customize API endpoint, session management, styling
+- 📱 **Responsive** - Works great on mobile and desktop
+- 🎯 **TypeScript** - Full type safety out of the box
+- ♿ **Accessible** - Built on Radix UI primitives
+## Installation
+```bash
+npm install @yourusername/ai-chat
+# or
+yarn add @yourusername/ai-chat
+# or
+pnpm add @yourusername/ai-chat
+```
+### Peer Dependencies
+This package requires React 18+ or React 19+:
+```bash
+npm install react react-dom
+```
+## Quick Start
+```tsx
+import { AIChat } from "@yourusername/ai-chat";
+import "@yourusername/ai-chat/styles";
+function App() {
+  return (
+    <AIChat
+      apiUrl="https://your-api-endpoint.com"
+      sessionId="user-123"
+      title="My AI Assistant"
+    />
+  );
+}
+```
+## Tailwind CSS Setup
+This component uses Tailwind CSS. Add the component path to your `tailwind.config.js`:
+```js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    "./app/**/*.{js,ts,jsx,tsx}",
+    "./components/**/*.{js,ts,jsx,tsx}",
+    // Add this line:
+    "./node_modules/@yourusername/ai-chat/**/*.{js,ts,jsx,tsx}",
+  ],
+  // ... rest of your config
+};
+```
+Or if using Tailwind v4, add to your CSS:
+```css
+@import "tailwindcss";
+@import "@yourusername/ai-chat/styles";
+```
+## API Requirements
+Your API endpoint should accept POST requests to `/ask` with this format:
+**Request:**
+```json
+{
+  "session_id": "string",
+  "question": "string"
+}
+```
+**Response:**
+```json
+{
+  "response": "string"
+}
+```
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiUrl` | `string` | *required* | Your API endpoint URL |
+| `sessionId` | `string` | `"default-session"` | Session identifier for conversation context |
+| `title` | `string` | `"My AI Agent"` | Chat header title |
+| `initialMessages` | `Message[]` | `[]` | Pre-populate chat with messages |
+| `className` | `string` | `undefined` | Custom CSS class for container |
+| `onMessageSent` | `(message: Message) => void` | `undefined` | Callback when user sends a message |
+| `onResponseReceived` | `(message: Message) => void` | `undefined` | Callback when AI responds |
+| `onError` | `(error: Error) => void` | `undefined` | Callback when an error occurs |
+## Advanced Usage
+### With Custom Styling
+```tsx
+<AIChat
+  apiUrl="https://api.example.com"
+  className="max-w-4xl mx-auto shadow-lg"
+  title="Customer Support Bot"
+/>
+```
+### With Event Handlers
+```tsx
+<AIChat
+  apiUrl="https://api.example.com"
+  onMessageSent={(message) => {
+    // Track analytics
+    analytics.track("message_sent", { content: message.content });
+  }}
+  onResponseReceived={(message) => {
+    // Log responses
+    console.log("AI responded:", message.content);
+  }}
+  onError={(error) => {
+    // Handle errors
+    toast.error(error.message);
+  }}
+/>
+```
+### With Initial Messages
+```tsx
+const welcomeMessages = [
+  {
+    id: "1",
+    role: "assistant" as const,
+    content: "Hello! How can I help you today?",
+  },
+];
+<AIChat
+  apiUrl="https://api.example.com"
+  initialMessages={welcomeMessages}
+/>
+```
+### With Dynamic Session Management
+```tsx
+import { useUser } from "@/hooks/useUser";
+function ChatPage() {
+  const user = useUser();
+  return (
+    <AIChat
+      apiUrl={process.env.NEXT_PUBLIC_API_URL!}
+      sessionId={user.id}
+      title={`Chat with ${user.name}'s Assistant`}
+    />
+  );
+}
+```
+## TypeScript
+Full TypeScript support is included. Import types as needed:
+```tsx
+import type { Message, AIChatProps } from "@yourusername/ai-chat";
+const customMessage: Message = {
+  id: "123",
+  role: "user",
+  content: "Hello!",
+};
+```
+## Styling
+The component uses Tailwind CSS with custom theme variables. You can customize the appearance by:
+1. **Using Tailwind's dark mode**: The component automatically supports dark mode
+2. **Custom CSS variables**: Override theme colors in your global CSS
+3. **className prop**: Add custom Tailwind classes to the container
+### Custom Theme Colors
+```css
+@layer base {
+  :root {
+    --primary: oklch(0.205 0 0);
+    --primary-foreground: oklch(0.985 0 0);
+    /* ... other variables */
+  }
+  .dark {
+    --primary: oklch(0.922 0 0);
+    --primary-foreground: oklch(0.205 0 0);
+    /* ... other variables */
+  }
+}
+```
+## Framework Support
+### Next.js (App Router)
+```tsx
+"use client";
+import { AIChat } from "@yourusername/ai-chat";
+import "@yourusername/ai-chat/styles";
+export default function ChatPage() {
+  return <AIChat apiUrl={process.env.NEXT_PUBLIC_API_URL!} />;
+}
+```
+### Next.js (Pages Router)
+```tsx
+import { AIChat } from "@yourusername/ai-chat";
+import "@yourusername/ai-chat/styles";
+export default function ChatPage() {
+  return <AIChat apiUrl={process.env.NEXT_PUBLIC_API_URL!} />;
+}
+```
+### Vite + React
+```tsx
+import { AIChat } from "@yourusername/ai-chat";
+import "@yourusername/ai-chat/styles";
+function App() {
+  return <AIChat apiUrl={import.meta.env.VITE_API_URL} />;
+}
+```
+### Create React App
+```tsx
+import { AIChat } from "@yourusername/ai-chat";
+import "@yourusername/ai-chat/styles";
+function App() {
+  return <AIChat apiUrl={process.env.REACT_APP_API_URL} />;
+}
+```
+## Examples
+Check out the [examples directory](./examples) for complete working examples with:
+- Next.js App Router
+- Vite + React
+- Custom styling
+- Advanced features
+## Browser Support
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari 14+
+- Mobile browsers (iOS Safari, Chrome Android)
+## Contributing
+Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md) first.
+## License
+MIT © [Your Name]
+## Related
+- [Radix UI](https://radix-ui.com/) - Accessible component primitives
+- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS framework
+- [shadcn/ui](https://ui.shadcn.com/) - Re-usable components built with Radix UI
+## Support
+- 📖 [Documentation](https://github.com/yourusername/ai-chat#readme)
+- 🐛 [Issue Tracker](https://github.com/yourusername/ai-chat/issues)
+- 💬 [Discussions](https://github.com/yourusername/ai-chat/discussions)