@enjoys/react-chatbot-plugin 1.2.0 → 1.3.0

package/README.md

@@ -1,8 +1,25 @@
-# @enjoys/react-chatbot-plugin
+<p align="center">
+  <img src="https://img.shields.io/npm/v/@enjoys/react-chatbot-plugin?color=6C5CE7&style=for-the-badge" alt="npm version" />
+  <img src="https://img.shields.io/npm/dm/@enjoys/react-chatbot-plugin?color=A29BFE&style=for-the-badge" alt="npm downloads" />
+  <img src="https://img.shields.io/bundlephobia/minzip/@enjoys/react-chatbot-plugin?color=00b894&style=for-the-badge" alt="bundle size" />
+  <img src="https://img.shields.io/npm/l/@enjoys/react-chatbot-plugin?color=fd79a8&style=for-the-badge" alt="license" />
+  <img src="https://img.shields.io/github/stars/enjoys-in/react-chatbot-plugin?color=fdcb6e&style=for-the-badge" alt="stars" />
+</p>
 
-A customizable, plugin-based chatbot widget for React — like tawk.to but fully programmable.
+<h1 align="center">@enjoys/react-chatbot-plugin</h1>
 
-[![npm](https://img.shields.io/npm/v/@enjoys/react-chatbot-plugin)](https://www.npmjs.com/package/@enjoys/react-chatbot-plugin)
+<p align="center">
+  A customizable, plugin-based chatbot widget for React — like tawk.to but fully programmable.
+</p>
+
+<p align="center">
+  <a href="https://github.com/enjoys-in/react-chatbot-plugin">GitHub</a> ·
+  <a href="https://www.npmjs.com/package/@enjoys/react-chatbot-plugin">npm</a> ·
+  <a href="https://github.com/enjoys-in/react-chatbot-plugin/issues">Report Bug</a> ·
+  <a href="https://github.com/enjoys-in/react-chatbot-plugin/issues">Request Feature</a>
+</p>
+
+---
 
 ## Features
 
@@ -14,6 +31,7 @@ A customizable, plugin-based chatbot widget for React — like tawk.to but fully
 - **Slash commands** — `/help`, `/back`, `/cancel`, `/restart` built-in
 - **Custom header/input** — Swap the header or input with your own React components
 - **Forms** — Text, select, radio, checkbox, file upload, with validation
+- **Custom form fields** — Replace any form field type with your own React component
 - **Theming** — Light/dark mode, CSS variables, glassmorphism design
 - **File uploads** — Drag & drop, preview, size/count limits
 - **Emoji picker** — Built-in emoji selector
@@ -25,6 +43,10 @@ A customizable, plugin-based chatbot widget for React — like tawk.to but fully
 ```bash
 npm install @enjoys/react-chatbot-plugin
 # or
+yarn add @enjoys/react-chatbot-plugin
+# or
+pnpm add @enjoys/react-chatbot-plugin
+# or
 bun add @enjoys/react-chatbot-plugin
 ```
 
@@ -57,14 +79,32 @@ function App() {
     <ChatBot
       flow={flow}
       header={{ title: 'Acme Support', subtitle: 'Online', showRestart: true }}
-      callbacks={{
-        onFlowEnd: (data) => console.log('Flow ended:', data),
-      }}
     />
   );
 }
 ```
 
+## Documentation
+
+Full documentation is available in the [`docs/`](./docs/) folder:
+
+| # | Guide | Description |
+|---|-------|-------------|
+| 1 | [Getting Started](./docs/getting-started.md) | Installation, quick start, minimal example |
+| 2 | [Basic Flows](./docs/basic-flows.md) | Steps, messages, quick replies, delays |
+| 3 | [Forms & Validation](./docs/forms.md) | All 15 field types, validation rules, login forms |
+| 4 | [Conditional Branching](./docs/conditional-branching.md) | If/else routing based on collected data |
+| 5 | [Async Actions](./docs/async-actions.md) | API calls, progress messages, error handling |
+| 6 | [Custom Components](./docs/custom-components.md) | React widgets inside flow steps |
+| 7 | [Dynamic Routing](./docs/dynamic-routing.md) | Route based on API response status |
+| 8 | [Theming & Styling](./docs/theming.md) | Colors, CSS variables, dark mode |
+| 9 | [Plugins](./docs/plugins.md) | Built-in & custom plugins |
+| 10 | [Slash Commands](./docs/slash-commands.md) | /help, /back, /restart, /cancel |
+| 11 | [File Upload](./docs/file-upload.md) | Drag & drop, restrictions, previews |
+| 12 | [Custom Header & Input](./docs/custom-header-input.md) | Replace header/input with React components |
+| 13 | [Advanced Patterns](./docs/advanced-patterns.md) | E-commerce bot, onboarding wizard, full examples |
+| 14 | [API Reference](./docs/api-reference.md) | All types, props, and exports |
+
 ## Props
 
 | Prop | Type | Description |
@@ -92,439 +132,16 @@ function App() {
 | `launcherIcon` | `ReactNode` | Custom launcher icon |
 | `closeIcon` | `ReactNode` | Custom close icon |
 | `zIndex` | `number` | CSS z-index |
+| `renderFormField` | `FormFieldRenderMap` | Custom renderers for form field types |
 | `className` | `string` | Root element class name |
 
-## Conversation Flows
-
-Flows are JSON objects with steps. Each step can have messages, quick replies, forms, conditional branching, and delays.
-
-```ts
-const flow: FlowConfig = {
-  startStep: 'welcome',
-  steps: [
-    {
-      id: 'welcome',
-      message: 'Welcome! What brings you here?',
-      quickReplies: [
-        { label: 'Buy', value: 'buy', next: 'purchase' },
-        { label: 'Help', value: 'help', next: 'support' },
-      ],
-    },
-    {
-      id: 'purchase',
-      message: 'Great choice!',
-      form: {
-        id: 'order',
-        title: 'Order Details',
-        fields: [
-          { name: 'email', type: 'email', label: 'Email', required: true },
-          { name: 'quantity', type: 'number', label: 'Quantity', required: true },
-        ],
-        submitLabel: 'Place Order',
-      },
-      next: 'thanks',
-    },
-    {
-      id: 'support',
-      message: 'Please describe your issue.',
-    },
-    {
-      id: 'thanks',
-      message: 'Order placed! We will email you shortly.',
-    },
-  ],
-};
-```
-
-### Step Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `id` | `string` | Unique step identifier |
-| `message` | `string` | Single bot message |
-| `messages` | `string[]` | Multiple bot messages |
-| `quickReplies` | `FlowQuickReply[]` | Clickable option buttons |
-| `form` | `FormConfig` | Inline form |
-| `next` | `string` | Next step ID (auto-advance) |
-| `delay` | `number` | Typing delay in ms (default: 500) |
-| `condition` | `FlowCondition` | Conditional branching |
-| `component` | `string` | Key into `components` map — renders a custom React widget |
-| `asyncAction` | `FlowAsyncAction` | Async action to run when the step is entered |
-
-### Conditional Branching
-
-```ts
-{
-  id: 'check_age',
-  message: 'Checking your age...',
-  condition: {
-    field: 'age',
-    operator: 'gt',  // eq, neq, contains, gt, lt
-    value: 18,
-    then: 'adult_flow',
-    else: 'minor_flow',
-  },
-}
-```
-
-## Async Actions
-
-Run API calls, validations, or any async work when a step is entered. The chat shows real-time progress messages and routes based on the result.
-
-```tsx
-import type { FlowConfig, FlowActionResult, ActionContext } from '@enjoys/react-chatbot-plugin';
-
-const flow: FlowConfig = {
-  startStep: 'collect_email',
-  steps: [
-    {
-      id: 'collect_email',
-      message: 'Enter your email to verify:',
-      form: {
-        id: 'email-form',
-        title: 'Email Verification',
-        fields: [{ name: 'email', type: 'email', label: 'Email', required: true }],
-        submitLabel: 'Verify',
-      },
-      next: 'verify',
-    },
-    {
-      id: 'verify',
-      message: 'Starting verification...',
-      asyncAction: {
-        handler: 'verify-email',        // key into actionHandlers
-        loadingMessage: '🔄 Verifying...', // shown while running
-        successMessage: '✅ Verified!',    // shown on success
-        errorMessage: '❌ Failed.',        // shown on error/throw
-        onSuccess: 'done',                // next step on success
-        onError: 'retry',                 // next step on error
-      },
-    },
-    { id: 'done', message: 'Your email is verified! 🎉' },
-    {
-      id: 'retry',
-      message: 'Verification failed. Try again?',
-      quickReplies: [
-        { label: 'Retry', value: 'retry', next: 'collect_email' },
-      ],
-    },
-  ],
-};
-
-<ChatBot
-  flow={flow}
-  actionHandlers={{
-    'verify-email': async (data, ctx) => {
-      ctx.updateMessage('📡 Contacting server...');   // update status message in real-time
-      await fetch('/api/verify', { method: 'POST', body: JSON.stringify(data) });
-      ctx.updateMessage('🔐 Validating...');
-      // return result — status determines routing
-      return { status: 'success', data: { verified: true } };
-    },
-  }}
-/>
-```
-
-### FlowAsyncAction Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `handler` | `string` | Key into `actionHandlers` prop |
-| `loadingMessage` | `string` | Message shown while running (default: "Processing...") |
-| `successMessage` | `string` | Message shown on success |
-| `errorMessage` | `string` | Message shown on error or exception |
-| `onSuccess` | `string` | Next step ID on success |
-| `onError` | `string` | Next step ID on error |
-| `routes` | `Record<string, string>` | Map of `result.status` → step ID for custom routing |
-
-### ActionContext
-
-| Method | Description |
-|--------|-------------|
-| `updateMessage(text)` | Update the loading/status message text in real-time |
-
-### FlowActionResult
-
-Returned by action handlers to control routing and data:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `status` | `string` | `'success'`, `'error'`, or any custom string for route matching |
-| `data` | `Record<string, unknown>` | Data to merge into collected data |
-| `message` | `string` | Override the success/error message |
-| `next` | `string` | Override all routing — go directly to this step |
-
-**Routing priority:** `result.next` → `routes[status]` → `onSuccess/onError` → `step.next`
-
-## Custom Step Components
-
-Render your own interactive React widgets inside flow steps. Components receive collected data and an `onComplete` callback to continue the flow.
-
-```tsx
-import type { StepComponentProps } from '@enjoys/react-chatbot-plugin';
-
-const PlanSelector: React.FC<StepComponentProps> = ({ data, onComplete }) => (
-  <div>
-    <p>Hi {data.name as string}! Choose a plan:</p>
-    <button onClick={() => onComplete({ status: 'success', data: { plan: 'basic' }, next: 'basic_info' })}>
-      Basic — $9/mo
-    </button>
-    <button onClick={() => onComplete({ status: 'success', data: { plan: 'pro' }, next: 'pro_info' })}>
-      Pro — $29/mo
-    </button>
-  </div>
-);
-
-const flow: FlowConfig = {
-  startStep: 'choose_plan',
-  steps: [
-    {
-      id: 'choose_plan',
-      message: 'Select your plan:',
-      component: 'PlanSelector',   // key into components map
-    },
-    { id: 'basic_info', message: 'Basic plan selected!' },
-    { id: 'pro_info', message: 'Pro plan selected!' },
-  ],
-};
-
-<ChatBot
-  flow={flow}
-  components={{ PlanSelector }}   // register your components here
-/>
-```
-
-### StepComponentProps
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `stepId` | `string` | The step ID that owns this component |
-| `data` | `Record<string, unknown>` | All collected flow/form data |
-| `onComplete` | `(result?: FlowActionResult) => void` | Call to complete the step and route to the next |
-
-## Dynamic Routing
-
-Use `asyncAction.routes` to map API result statuses to different steps:
-
-```tsx
-{
-  id: 'check_account',
-  message: 'Looking up your account...',
-  asyncAction: {
-    handler: 'check-account',
-    loadingMessage: '🔍 Searching...',
-    routes: {
-      admin: 'admin_panel',    // result.status === 'admin'
-      vip: 'vip_welcome',      // result.status === 'vip'
-      active: 'dashboard',     // result.status === 'active'
-      not_found: 'register',   // result.status === 'not_found'
-    },
-  },
-}
-```
-
-The action handler returns the status that determines which route to take:
-
-```ts
-'check-account': async (data, ctx) => {
-  const user = await api.lookup(data.username);
-  if (!user) return { status: 'not_found' };
-  return { status: user.role, data: { userId: user.id } };
-}
-```
-
-## Slash Commands
-
-Users can type these commands in the chat input:
-
-| Command | Description |
-|---------|-------------|
-| `/help` | Show available commands |
-| `/back` | Go back to the previous step |
-| `/cancel` | Same as /back — cancel current step |
-| `/restart` | Restart the conversation from the beginning |
-
-## Custom Header & Input
-
-Use `renderHeader` and `renderInput` to replace the default header or input with your own components. Both receive a `ChatRenderContext` object and the default element:
-
-```tsx
-<ChatBot
-  flow={flow}
-  renderHeader={(ctx, defaultHeader) => (
-    <div style={{ padding: 16, background: '#333', color: '#fff' }}>
-      <h3>My Custom Header</h3>
-      <p>Step: {ctx.currentStepId ?? 'none'}</p>
-      <button onClick={ctx.restartSession}>Restart</button>
-      <button onClick={ctx.toggleChat}>Close</button>
-    </div>
-  )}
-  renderInput={(ctx, defaultInput) => {
-    // Use the default input but wrap it
-    return (
-      <div>
-        {defaultInput}
-        <small>Step: {ctx.currentStepId}</small>
-      </div>
-    );
-  }}
-/>
-```
-
-### ChatRenderContext
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `currentStepId` | `string \| null` | Current flow step ID |
-| `isOpen` | `boolean` | Whether the chat window is open |
-| `messages` | `ChatMessage[]` | All messages |
-| `collectedData` | `Record<string, unknown>` | Collected form/flow data |
-| `toggleChat` | `() => void` | Open/close the chat |
-| `restartSession` | `() => void` | Restart from beginning |
-| `sendMessage` | `(text: string) => void` | Send a message programmatically |
-
-## Theming
-
-```tsx
-<ChatBot
-  theme={{
-    primaryColor: '#6C5CE7',
-    headerBg: 'linear-gradient(135deg, #6C5CE7, #A29BFE)',
-    borderRadius: '20px',
-    mode: 'dark', // or 'light'
-    fontFamily: '"Inter", sans-serif',
-    windowWidth: '400px',
-    windowHeight: '600px',
-  }}
-/>
-```
-
-All theme values are also exposed as CSS variables (`--cb-primary`, `--cb-header-bg`, etc.).
-
-## Plugins
-
-### Built-in Plugins
-
-```tsx
-import { analyticsPlugin, webhookPlugin, persistencePlugin } from '@enjoys/react-chatbot-plugin';
-
-<ChatBot
-  plugins={[
-    analyticsPlugin({
-      onTrack: (event, data) => console.log(event, data),
-    }),
-    webhookPlugin({
-      url: '/api/chatbot-webhook',
-      events: ['message', 'submit'],
-    }),
-    persistencePlugin({
-      storageKey: 'my_chat',
-      storage: 'local', // or 'session'
-    }),
-  ]}
-/>
-```
-
-### Custom Plugin
-
-```ts
-import type { ChatPlugin } from '@enjoys/react-chatbot-plugin';
-
-const myPlugin: ChatPlugin = {
-  name: 'my-plugin',
-  onInit(ctx) {
-    console.log('Chat initialized');
-  },
-  onMessage(message, ctx) {
-    console.log('Message:', message);
-  },
-  onSubmit(data, ctx) {
-    console.log('Form submitted:', data);
-  },
-  onDestroy(ctx) {
-    console.log('Chat destroyed');
-  },
-};
-```
-
-### Plugin Context
-
-| Method | Description |
-|--------|-------------|
-| `sendMessage(text)` | Send a user message |
-| `addBotMessage(text)` | Add a bot message |
-| `getMessages()` | Get all messages |
-| `getData()` | Get collected data |
-| `setData(key, value)` | Set data |
-| `on(event, handler)` | Subscribe to events |
-| `emit(event, ...args)` | Emit events |
-
-## Forms
-
-Forms can be used in flows or as a login screen:
-
-```ts
-const form: FormConfig = {
-  id: 'contact',
-  title: 'Contact Us',
-  description: 'Fill out the form below',
-  fields: [
-    { name: 'name', type: 'text', label: 'Name', required: true },
-    { name: 'email', type: 'email', label: 'Email', required: true,
-      validation: { pattern: '^[^@]+@[^@]+\\.[^@]+$', message: 'Invalid email' } },
-    { name: 'priority', type: 'select', label: 'Priority', options: [
-      { label: 'Low', value: 'low' },
-      { label: 'High', value: 'high' },
-    ]},
-    { name: 'message', type: 'textarea', label: 'Message' },
-    { name: 'file', type: 'file', label: 'Attachment', accept: 'image/*,.pdf' },
-  ],
-  submitLabel: 'Send',
-};
-```
-
-**Supported field types:** `text`, `email`, `password`, `number`, `tel`, `url`, `textarea`, `select`, `multiselect`, `radio`, `checkbox`, `file`, `date`, `time`, `hidden`
-
-## Callbacks
-
-```tsx
-<ChatBot
-  callbacks={{
-    onOpen: () => {},
-    onClose: () => {},
-    onMessageSend: (msg) => {},
-    onMessageReceive: (msg) => {},
-    onSubmit: (data) => {},
-    onLogin: (data) => {},
-    onFormSubmit: (formId, data) => {},
-    onQuickReply: (value, label) => {},
-    onFileUpload: (files) => {},
-    onFlowEnd: (collectedData) => {},
-    onError: (error) => {},
-    onEvent: (event, payload) => {},
-  }}
-/>
-```
-
-## File Upload
-
-```tsx
-<ChatBot
-  fileUpload={{
-    enabled: true,
-    accept: 'image/*,.pdf,.doc,.docx',
-    multiple: true,
-    maxSize: 5 * 1024 * 1024, // 5MB
-    maxFiles: 3,
-  }}
-/>
-```
-
 ## Exported Components
 
 All internal components are exported for advanced use cases:
 
-`ChatBot`, `ChatHeader`, `ChatInput`, `ChatWindow`, `Launcher`, `MessageBubble`, `MessageList`, `QuickReplies`, `TypingIndicator`, `WelcomeScreen`, `LoginScreen`, `Branding`, `EmojiPicker`, `FileUploadButton`, `FilePreviewList`, `DynamicForm`, `TextField`, `SelectField`, `RadioField`, `CheckboxField`, `FileUploadField`
+**UI:** `ChatBot`, `ChatHeader`, `ChatInput`, `ChatWindow`, `Launcher`, `MessageBubble`, `MessageList`, `QuickReplies`, `TypingIndicator`, `WelcomeScreen`, `LoginScreen`, `Branding`, `EmojiPicker`, `FileUploadButton`, `FilePreviewList`, `DynamicForm`
+
+**Forms:** `TextField`, `SelectField`, `RadioField`, `CheckboxField`, `FileUploadField`
 
 **Icons:** `SendIcon`, `ChatBubbleIcon`, `CloseIcon`, `MinimizeIcon`, `EmojiIcon`, `AttachmentIcon`, `FileIcon`, `ImageIcon`, `RemoveIcon`, `RestartIcon`
 
@@ -532,19 +149,31 @@ All internal components are exported for advanced use cases:
 
 **Theme utilities:** `resolveTheme`, `buildStyles`, `buildCSSVariables`
 
+**Built-in plugins:** `analyticsPlugin`, `webhookPlugin`, `persistencePlugin`
+
 ## Development
 
 ```bash
 # Install dependencies
 bun install
 
-# Run demo
+# Run demo (14 interactive demos)
 bun run dev
 
 # Build library
 bun run build
 ```
 
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
 ## License
 
-MIT
+MIT © [Enjoys](https://github.com/enjoys-in)