@evelan/jexity-widget 0.2.0 → 0.3.0-canary.4

package/README.md

@@ -8,8 +8,9 @@ Embeddable AI chat widget for any website. Add customer support chat with a sing
 
 ```html
 <script
-  src="https://unpkg.com/@evelan/jexity-widget/dist/widget.js"
-  data-org-id="YOUR_ORG_ID"
+  src="https://cdn.evelan.de/widget/latest/widget.js"
+  data-org-slug="YOUR_ORG_SLUG"
+  async
 ></script>
 ```
 
@@ -23,10 +24,11 @@ npm install @evelan/jexity-widget
 import { JexityChat } from '@evelan/jexity-widget'
 
 const chat = JexityChat({
-  orgId: 'YOUR_ORG_ID',
+  orgSlug: 'YOUR_ORG_SLUG',
 })
 
-// Later: chat.shutdown()
+// Later:
+chat.shutdown()
 ```
 
 ### React Provider
@@ -36,7 +38,7 @@ import { JexityChatProvider, useJexityChat } from '@evelan/jexity-widget/react'
 
 function App() {
   return (
-    <JexityChatProvider orgId="YOUR_ORG_ID">
+    <JexityChatProvider orgSlug="YOUR_ORG_SLUG">
       <HomePage />
     </JexityChatProvider>
   )
@@ -48,40 +50,184 @@ function HomePage() {
 }
 ```
 
+---
+
 ## Configuration
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `orgId` | `string` | *required* | Your organization ID |
+| `orgSlug` | `string` | **required** | Your organization slug (e.g. `acme-corp`) |
 | `container` | `string \| HTMLElement` | auto-created `div` | CSS selector or element to mount into |
 | `position` | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Widget position on screen |
-| `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Color theme |
-| `greeting` | `string` | `'Hi there! How can I help?'` | Initial bot message |
+| `colorScheme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Force color scheme; `'auto'` follows system preference |
 | `title` | `string` | `'Jexity Assistant'` | Chat window header title |
-| `primaryColor` | `string` | `'#0070f3'` | Brand color (hex) |
+| `greeting` | `string` | `'Hi! How can I help?'` | Initial bot message shown on open |
+| `primaryColor` | `string` | `'#0070f3'` | Shorthand brand color — tints FAB, header, user bubbles, send button |
+| `accentColor` | `string` | — | Secondary accent color |
+| `fontFamily` | `string` | — | Override widget font family |
+| `fontSize` | `number` | — | Base font size in px |
+| `borderRadius` | `string` | — | Override widget corner radius (e.g. `'8px'`) |
+| `windowWidth` | `number` | — | Chat window width in px |
+| `windowHeight` | `number` | — | Chat window height in px |
+| `triggerIcon` | `'chat' \| 'bot' \| 'sparkles'` | `'chat'` | Floating action button icon |
+| `triggerRadius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `'full'` | FAB border radius shape |
+| `triggerLabel` | `string` | — | Text label shown next to the FAB |
+| `hideBranding` | `boolean` | `false` | Hide the "Powered by Jexity" footer |
+| `locale` | `string` | browser / `'de'` | Force locale (`'de'` \| `'en'`). Overrides browser detection |
+| `parentOrigin` | `string` | `window.location.origin` | Trusted origin for postMessage dashboard preview updates |
+| `theme` | `JexityTheme` | — | Granular per-element color overrides (see below) |
+
+### Granular Theme Overrides
+
+`theme` lets you override individual element colors. Unset keys fall back to `primaryColor` or brand defaults.
+
+```ts
+JexityChat({
+  orgSlug: 'acme',
+  theme: {
+    bg: {
+      trigger: '#1a1a2e',    // FAB background
+      header: '#16213e',     // Chat header
+      msgUser: '#0f3460',    // User bubble background
+      msgBot: '#f5f5f5',     // Bot bubble background
+      window: '#ffffff',     // Chat window background
+      sendBtn: '#e94560',    // Send button background
+    },
+    text: {
+      header: '#ffffff',     // Header text/icon color
+      msgUser: '#ffffff',    // User bubble text
+      msgBot: '#333333',     // Bot bubble text
+      main: '#212121',       // Primary body text
+      muted: '#888888',      // Secondary/muted text
+    },
+    border: {
+      window: '#e0e0e0',     // Window border
+      input: '#cccccc',      // Input field border
+    },
+  },
+})
+```
+
+---
 
 ## Programmatic API
 
 ```ts
 const chat = JexityChat(options)
 
-chat.open()      // Open the chat window
-chat.close()     // Close the chat window
-chat.toggle()    // Toggle open/closed
-chat.shutdown()  // Remove widget from DOM
-chat.isOpen      // readonly boolean
+chat.open()                    // Open the chat window
+chat.close()                   // Close the chat window
+chat.toggle()                  // Toggle open/closed
+chat.shutdown()                // Remove widget from DOM
+chat.isOpen                    // readonly boolean — current open state
+chat.subscribe(cb)             // Subscribe to open/close changes
+                               // Returns unsubscribe function
+
+// IIFE global (script tag):
+window.JexityChat.open()
+window.JexityChat.close()
+window.JexityChat.toggle()
+window.JexityChat.shutdown()
+```
+
+---
+
+## IIFE (Script Tag) Attributes
+
+All options can be set as `data-*` attributes on the `<script>` tag:
+
+```html
+<script
+  src="https://cdn.evelan.de/widget/latest/widget.js"
+  data-org-slug="acme-corp"
+  data-locale="de"
+  data-primary-color="#ff6600"
+  data-trigger-icon="sparkles"
+  data-trigger-radius="lg"
+  data-trigger-label="Chat with us"
+  data-hide-branding="true"
+  async
+></script>
 ```
 
-## Script Tag Global
+Then control programmatically after load:
 
 ```html
-<script src="https://cdn.evelan.de/widget/latest/widget.js" data-org-id="YOUR_ORG_ID"></script>
 <script>
   window.JexityChat.open()
   window.JexityChat.shutdown()
 </script>
 ```
 
+---
+
+## Build Outputs
+
+```
+dist/
+  widget.js          ← IIFE for <script> embed (CDN)
+  index.mjs          ← ESM for bundlers (npm)
+  react.mjs          ← React bindings (externalizes react + core)
+  types/index.d.ts   ← TypeScript declarations (core)
+  types/react.d.ts   ← TypeScript declarations (React)
+```
+
+Target sizes: IIFE ≤ 32 KB · ESM ≤ 42 KB (gzipped)
+
+---
+
+## Development
+
+```bash
+# From repo root:
+pnpm dev --filter @evelan/jexity-widget
+
+# Or directly:
+cd apps/widget
+pnpm dev
+```
+
+Open **`http://localhost:3002`** — the dev playground with live config controls.
+
+### Environment variables
+
+Create `apps/widget/.env.local`:
+
+```bash
+# Convex HTTP site URL — used to fetch widget config on mount.
+# Copy from packages/backend/.env.local (CONVEX_SITE_URL).
+# Dev deployment:  sensible-anaconda-990.eu-west-1.convex.site
+# Prod deployment: festive-<...>.convex.site  (set in GitHub Actions Variable)
+VITE_CONVEX_SITE_URL=https://<your-dev-deployment>.convex.site
+
+# Reserved — not consumed yet. Future escape hatch if we ever swap Convex for
+# a traditional REST backend (Express, Fastify, etc.). Once wired, widget code
+# will read this instead of VITE_CONVEX_SITE_URL so the backend is hot-swappable
+# via env alone. Set in GitHub Actions Secret: VITE_API_BASE_URL.
+# VITE_API_BASE_URL=https://api.example.com
+```
+
+### URL Parameters
+
+| Parameter | Example | Purpose |
+|-----------|---------|---------|
+| `?orgSlug=` | `?orgSlug=demo` | Set org slug (default: `dev_local`) |
+| `?primaryColor=` | `?primaryColor=%230070f3` | Set primary color |
+| `?locale=` | `?locale=en` | Lock locale |
+| `?position=` | `?position=bottom-left` | Widget position |
+| `?title=` | `?title=My+Assistant` | Widget title |
+| `?hideBranding=true` | — | Hide footer branding |
+| `?skipHomeScreen=true` | — | Open directly to chat (skip landing) |
+
+### Build
+
+```bash
+pnpm build          # Full build (all 5 outputs)
+pnpm check-types    # Type-check only (fast)
+```
+
+---
+
 ## License
 
 MIT