@channlize/react 0.1.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @channlize/react
 
+## 0.4.0
+
+### Minor Changes
+
+- Release every `@channlize/*` package under one shared version. From 0.4.0 on, core, react, mcp and skills always publish together at the same version, so matching versions work together.
+- 7b82215: Add a `debug` option to `useChatSession` and `SupportChat` (also through `ChannlizeChat`'s `chatProps`). The chat no longer writes to the console unless `debug` is on; it used to log every session step and SSE message. `ChannlizeProvider` keeps one client per configuration instead of creating one on every render, the chat calls the latest `onMessage` / `onError` without reopening the stream, and `UseContactFormOptions`, `UseContactFormReturn` and `ChannlizeProviderProps` are exported.
+
+### Patch Changes
+
+- 5663cd2: Make `@channlize/core` the single source for what the packages share.
+
+  - core exports `DEFAULT_BASE_URL`, `DEFAULT_TIMEOUT`, `EVENT_SEVERITIES`, `EVENT_KEY_PATTERN`, `isValidEventKey`, `keyKind` (widget vs. server key), `readChannlizeEnv` (the `CHANNLIZE_*` variables) and `parseApiError` (the API's error shape). `createNotifier`, the client and `@channlize/mcp` use them instead of their own copies.
+  - `ChannlizeError` gains `requestId` and `details` (the API's error body, e.g. `limit`, `used` and `resetAt` on a plan-limit 429). When a legacy route puts its human-readable text in `error`, it becomes the message instead of `HTTP <status>`.
+  - The chat types document where the API differs from them (ISO string timestamps, session summaries without `messages`).
+  - `@channlize/react` and `@channlize/mcp` re-export the error classes as values, so `instanceof` works without importing core.
+  - mcp tool errors no longer end with a doubled period when a core error message ends with one.
+
+- Updated dependencies [5663cd2]
+- Updated dependencies
+  - @channlize/core@0.4.0
+
+## 0.3.0
+
+### Minor Changes
+
+- ad8f04d: Redesign `ContactForm` to match the chat widget: scoped styles, `theme` (light / dark / auto / system), `primaryColor`, labels and placeholders, inline validation with accessible errors, loading / success / error states, a honeypot spam guard, and optional company and topic fields (`fields`, `topics`, `defaultValues`). Existing props keep working; `onSuccess` now also receives the API response. Export `ContactFormProps`, `ContactFormLabels` and `defaultContactFormLabels`.
+
+### Patch Changes
+
+- Updated dependencies [69f414f]
+  - @channlize/core@0.2.1
+
+## 0.2.0
+
+### Minor Changes
+
+- db7da26: Redesign the live-chat widget (`ChannlizeChat` / `SupportChat`).
+
+  - Header: brand avatar slot, title, and a calm status line ("Online · Replies in a few minutes"). The close button no longer overlaps anything; "End conversation" moved into a menu with a confirmation step; a clear minimize button.
+  - Messages: grouped by author with agent name and avatar, day separators, one timestamp per group (full date on hover), better bubble shapes, wrapping of long words and URLs, safe link detection (http/https only, no HTML), image and file attachment cards, and optimistic sending with "Sending…" / "Not sent · Retry · Remove".
+  - Welcome screen with `greeting`, `welcomeMessage` and optional `suggestions`.
+  - Composer: auto-growing textarea (Enter sends, Shift+Enter new line), send icon button disabled when empty, attach button with `allowAttachments`, `maxLength` counter, "Write a message…" placeholder.
+  - Connection: status and "Reconnecting…" banner are debounced, so the routine SSE reconnect every ~50s never flickers; a lost connection shows a banner with Retry.
+  - Theming: light and dark (`theme`, follows `prefers-color-scheme` by default), `primaryColor` / `primaryTextColor` with automatic readable text color; the hard-coded blue-to-purple gradient is gone. Existing `styles`, `buttonColors`, `className` props keep working.
+  - Launcher: new icon, unread badge counting agent replies received while closed (or `showBadge` + `unreadCount`), open/close animation that respects `prefers-reduced-motion`.
+  - Mobile: full-screen panel under 640px, safe-area insets, 16px input to avoid iOS zoom.
+  - Accessibility: the panel is a labelled dialog, focus moves in on open and back to the launcher on close, Esc closes, the message list is a polite live region, all icon buttons are labelled.
+  - Isolation: a scoped stylesheet with a reset under `.channlize-widget`; `ChannlizeChat` renders through a portal into `document.body`. Default `zIndex` is now `2147483000`.
+  - New props: `ChannlizeChat` `primaryColor`, `theme`; `SupportChat` `avatarUrl`, `avatar`, `statusText`, `greeting`, `welcomeMessage`, `suggestions`, `theme`, `primaryColor`, `primaryTextColor`, `locale`, `maxLength`, `allowEndChat`, `onMinimize`, `labels`. `useChatSession` returns `reconnect()`. Exported types: `SupportChatProps`, `SupportChatLabels`, `ChatTheme`, `ChannlizeChatProps`, `UseChatSessionOptions`, `UseChatSessionReturn`, and `defaultSupportChatLabels`.
+
+## 0.1.2
+
+### Patch Changes
+
+- c113208: Add Events: post a Slack message from your server when something happens.
+
+  - `@channlize/core`: `client.notify(event, data?, { idempotencyKey?, channel? })` and a standalone `createNotifier()` that reads `CHANNLIZE_SERVER_API_KEY` / `CHANNLIZE_API_KEY` and `CHANNLIZE_PROJECT_ID`. Both call `POST /v1/notify` with the server API key (write scope). Event keys and data can be typed with `createNotifier<AppEvents>()` or by augmenting `ChannlizeEvents`. `trackEvent` / `trackServerEvent` are unchanged and now documented as log tracking. Fix: an explicit `baseUrl: undefined` or `timeout: undefined` no longer overrides the defaults.
+  - `@channlize/mcp`: new `notify_event` tool, enabled with `--server-api-key` / `CHANNLIZE_SERVER_API_KEY`.
+  - `@channlize/react`: docs only. `useChannlizeAnalytics().track` is documented as log tracking.
+
+- Updated dependencies [c113208]
+  - @channlize/core@0.2.0
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -61,7 +61,7 @@ function App() {
   return (
     <ChannlizeProvider
       config={{
-        apiKey: 'your-api-key',
+        apiKey: 'your-widget-key',
         projectId: 'your-project-id',
       }}
     >
@@ -71,6 +71,8 @@ function App() {
 }
 ```
 
+`ContactForm`, `SupportChat` and the hooks below must be rendered inside `ChannlizeProvider` (`ChannlizeChat` includes it).
+
 ### Contact Form Component
 
 ```tsx
@@ -113,7 +115,7 @@ import { SupportChat } from '@channlize/react';
 function SupportPage() {
   return (
     <SupportChat
-      autoStart={true}
+      autoConnect={true}
       title="Customer Support"
       placeholder="How can we help you?"
       onMessage={(message) => {
@@ -158,7 +160,7 @@ function CustomContactForm() {
     await submit({
       name: 'John Doe',
       email: 'john@example.com',
-      message: 'Hello!',
+      message: 'Hello, I have a question about pricing.', // at least 10 characters
     });
   };
 
@@ -254,16 +256,18 @@ function CustomChat() {
 | `buttonElement` | `ReactNode` | - | Custom button (overrides default) |
 | `buttonIcon` | `ReactNode` | - | Custom icon (used if buttonElement not provided) |
 | `buttonSize` | `number` | `56` | Button size in pixels |
-| `buttonColors` | `{ background?: string; hover?: string; text?: string }` | Blue gradient | Button colors |
-| `chatProps` | `SupportChatProps` | `{}` | Props passed to internal SupportChat component |
+| `buttonColors` | `{ background?: string; hover?: string; text?: string }` | `primaryColor` | Launcher colors |
+| `primaryColor` | `string` | `'#2563eb'` | Accent color for the launcher, header, customer bubbles and send button (hex recommended; text on it is picked for contrast) |
+| `theme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Color scheme; `auto` follows `prefers-color-scheme` |
+| `chatProps` | `SupportChatProps` | `{}` | Props passed to internal SupportChat component (title, greeting, suggestions...) |
 | `defaultOpen` | `boolean` | `false` | Whether to start open |
-| `showBadge` | `boolean` | `false` | Whether to show unread count badge |
-| `unreadCount` | `number` | `0` | Unread message count |
-| `zIndex` | `number` | `1000` | CSS z-index |
-| `showOnMobile` | `boolean` | `true` | Whether to show on mobile devices |
+| `showBadge` | `boolean` | `false` | Show `unreadCount` instead of the built-in count of agent replies received while closed |
+| `unreadCount` | `number` | `0` | Unread message count (with `showBadge`) |
+| `zIndex` | `number` | `2147483000` | CSS z-index |
+| `showOnMobile` | `boolean` | `true` | Whether to show the launcher on screens under 640px |
 | `onOpen` | `() => void` | - | Callback when chat opens |
 | `onClose` | `() => void` | - | Callback when chat closes |
-| `enableAnimations` | `boolean` | `true` | Enable smooth animations |
+| `enableAnimations` | `boolean` | `true` | Enable animations (always reduced with `prefers-reduced-motion`) |
 | `buttonClassName` | `string` | `''` | Custom class for button container |
 | `chatClassName` | `string` | `''` | Custom class for chat container |
 
@@ -290,13 +294,25 @@ function CustomChat() {
   }}
 />
 
-// With custom chat options
+// Branding, greeting and quick suggestions
+<ChannlizeChat
+  config={{ apiKey: 'key', projectId: 'id' }}
+  primaryColor="#0f766e"
+  chatProps={{
+    title: 'Acme',
+    avatarUrl: 'https://acme.com/logo.png',
+    statusText: 'Replies in a few minutes',
+    greeting: 'Hi there!',
+    welcomeMessage: 'Ask us anything. We are here to help.',
+    suggestions: ['How does pricing work?', 'Talk to sales'],
+    allowAttachments: true,
+  }}
+/>
+
+// Inline style overrides still apply on top of the theme
 <ChannlizeChat
   config={{ apiKey: 'key', projectId: 'id' }}
   chatProps={{
-    title: "24/7 Support",
-    placeholder: "Ask us anything...",
-    showTimestamps: true,
     styles: {
       header: {
         background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
@@ -332,31 +348,78 @@ function CustomChat() {
 
 ### ContactForm
 
-A complete contact form component with validation and submission handling.
+A themed, accessible contact form that posts to Channlize (and from there to
+your Slack). Styles are scoped to `.channlize-contact`, so it looks the same on
+any page and never leaks into it. It has inline validation, a focus move to the
+first invalid field, errors linked to their fields with `aria-describedby`,
+loading, success and error states, and a hidden honeypot field against simple
+bots.
+
+```tsx
+<ContactForm
+  theme="auto"
+  primaryColor="#2563eb"
+  fields={{ company: 'optional' }}
+  topics={['Sales', 'Support', 'Billing']}
+  defaultValues={{ topic: searchParams.get('topic') ?? undefined }}
+  labels={{ footnote: 'We usually reply within one business day.' }}
+  onSuccess={({ conversationId }) => console.log('Sent', conversationId)}
+/>
+```
 
 **Props:**
-- `customFields?: Array<CustomField>` - Additional form fields
-- `onSuccess?: () => void` - Success callback
+- `customFields?: ContactFormCustomField[]` - Extra fields (`text`, `email`, `textarea`, `select`), sent as `customFields`
+- `onSuccess?: (response: CreateContactResponse) => void` - Success callback
 - `onError?: (error: Error) => void` - Error callback
-- `className?: string` - CSS class name
-- `styles?: ContactFormStyles` - Custom styles object
-- `submitText?: string` - Submit button text
-- `successMessage?: string` - Success message text
+- `className?: string` - CSS class name on the root
+- `styles?` - Inline style overrides: `form`, `field`, `label`, `input`, `textarea`, `button`, `error`, `success`
+- `submitText?: string` / `successMessage?: string` - Shortcuts for `labels.submit` / `labels.successMessage`
+- `theme?: 'light' | 'dark' | 'auto' | 'system'` - Colour scheme (default `'light'`; `auto` and `system` follow `prefers-color-scheme`)
+- `primaryColor?: string`, `primaryTextColor?: string` - Accent colour (button, focus ring) and the text on it
+- `variant?: 'card' | 'plain'` - `card` (default) draws a themed surface; `plain` inherits the host's background
+- `unstyled?: boolean` - Skip the built-in stylesheet (class names stay)
+- `fields?: { name?, company?, subject?, topic? }` - Each `'required' | 'optional' | 'hidden'` (defaults: name required, subject optional, company hidden, topic optional when `topics` is set). Email and message are always required.
+- `topics?: Array<string | { value: string; label?: string }>` - Shows a topic select. The chosen label is sent as `customFields.topic` and used as the subject when that is blank; `value` identifies the option for `defaultValues`
+- `defaultValues?: Partial<{ name, email, company, subject, topic, message }>` - Prefill; `topic` matches an option's value or label case-insensitively (e.g. `?topic=sales`)
+- `labels?: Partial<ContactFormLabels>` - Override any label, placeholder or message (see `defaultContactFormLabels`)
+- `minMessageLength?: number` (default `10`, what the API accepts), `maxMessageLength?: number` (default `5000`)
+- `honeypot?: boolean` - Hidden spam-trap field; a filled trap gets a fake success and nothing is sent (default `true`)
+- `showSuccessState?: boolean` - Show the built-in success screen (default `true`); when `false` the form clears and announces success
+- `idPrefix?: string` - Prefix of field ids (default `channlize`, e.g. `channlize-email`)
 
 ### SupportChat
 
-A real-time chat widget with message history and file attachments.
+A real-time chat panel with grouped messages, day separators, safe link
+detection, attachments, optimistic sending with retry, and a debounced
+connection status (routine stream reconnects never flash in the UI). It fills
+its parent, so give the parent a height.
 
 **Props:**
-- `autoStart?: boolean` - Auto-start chat session
+- `autoConnect?: boolean` - Start (or resume) the session on mount (default `true`)
 - `metadata?: Record<string, unknown>` - Session metadata
 - `onMessage?: (message: ChatMessage) => void` - New message callback
 - `onError?: (error: Error) => void` - Error callback
+- `sessionId?: string`, `persistSession?: boolean` (default `true`), `storageKey?: string` - Resume a session, and where its id is kept in `localStorage`
+- `debug?: boolean` - Log connection and session details to the console (default `false`)
 - `className?: string` - CSS class name
-- `styles?: SupportChatStyles` - Custom styles object
-- `title?: string` - Chat header title
-- `placeholder?: string` - Input placeholder text
-- `maxHeight?: string` - Maximum container height
+- `styles?` - Inline style overrides: `container`, `header`, `messagesContainer`, `message`, `userMessage`, `agentMessage`, `inputContainer`, `input`, `button`, `error`, `timestamp`
+- `title?: string` - Team or brand name in the header (default `'Support'`)
+- `avatarUrl?: string` / `avatar?: ReactNode` - Logo in the header and welcome screen (initials otherwise)
+- `statusText?: string` - Shown after "Online" (default `'Replies in a few minutes'`; `''` hides it)
+- `greeting?: string` / `welcomeMessage?: string` - Welcome screen copy
+- `suggestions?: string[]` - Quick replies on the welcome screen
+- `placeholder?: string` - Input placeholder (default `'Write a message…'`)
+- `sendButtonText?: string` - Accessible label of the send icon button
+- `showTimestamps?: boolean` - One time per message group, full date on hover (default `true`)
+- `allowAttachments?: boolean` - Show the attach button (default `false`)
+- `theme?: 'auto' | 'light' | 'dark'`, `primaryColor?: string`, `primaryTextColor?: string` - Theming
+- `locale?: string` - Locale for dates and times (default: browser)
+- `maxLength?: number` - Maximum message length (default `5000`)
+- `allowEndChat?: boolean` - "End conversation" in the header menu, with confirmation (default `true`)
+- `onMinimize?: () => void` - Shows a minimize button; Esc calls it
+- `labels?: Partial<SupportChatLabels>` - Override any UI string (see `defaultSupportChatLabels`)
+
+Keyboard: Enter sends, Shift+Enter adds a new line (on touch-only devices Enter adds a new line and the button sends).
 
 ## Hooks
 
@@ -384,6 +447,10 @@ Hook for managing chat sessions with real-time messaging.
 - `metadata?: Record<string, unknown>`
 - `onMessage?: (message: ChatMessage) => void`
 - `onError?: (error: ChannlizeError) => void`
+- `sessionId?: string` - Resume this session instead of the stored one
+- `persistSession?: boolean` - Keep the session id in `localStorage` so a reload resumes it (default `true`)
+- `storageKey?: string` - `localStorage` key (default `channlize_session_<widget key>`)
+- `debug?: boolean` - Log connection and session details to the console with a `[channlize]` prefix (default `false`). Failures are always reported through `error` and `onError`.
 
 **Returns:**
 - `session: ChatSession | null`
@@ -394,11 +461,25 @@ Hook for managing chat sessions with real-time messaging.
 - `sendMessage: (content: string, attachments?: File[]) => Promise<void>`
 - `startSession: () => Promise<void>`
 - `endSession: () => Promise<void>`
+- `reconnect: () => void` - Reopen the real-time stream after it failed (`error.code === 'SSE_ERROR'`)
+
+### useChannlizeAnalytics (log tracking)
+
+Records logs from the browser with the widget key; they show up under **Log tracking** in the dashboard.
+
+```tsx
+const { track } = useChannlizeAnalytics();
+track('cta_clicked', { properties: { section: 'hero' } });
+```
+
+To post a Slack message when something happens (a signup, a payment), use **Events** from your server — `createNotifier` / `client.notify` in [`@channlize/core`](../core/README.md#events-notify-slack-from-your-server). Events need a server API key, so they are never sent from the browser.
 
 ## Styling
 
 All components accept a `styles` prop for custom styling. You can also use CSS classes with the `className` prop. Components use semantic class names prefixed with `channlize-`.
 
+The chat widget ships its own small stylesheet, scoped under `.channlize-widget`, with a reset so host-page element styles (`button`, `h2`, `textarea`...) don't leak in, and nothing leaks out. `ChannlizeChat` renders into `document.body` through a portal so host transforms and `overflow` can't clip it. Theme tokens are CSS custom properties on `.channlize-widget` (`--chz-primary`, `--chz-on-primary`, `--chz-bg`, `--chz-text`, `--chz-muted`, `--chz-border`, `--chz-bubble`...) and can be overridden from your CSS.
+
 ### CSS Classes
 
 - `.channlize-contact-form`
@@ -408,7 +489,8 @@ All components accept a `styles` prop for custom styling. You can also use CSS c
 - `.channlize-chat-container`
 - `.channlize-chat-header`
 - `.channlize-chat-messages`
-- `.channlize-message`
+- `.channlize-chat-status` (`data-status="online|connecting|offline"`)
+- `.channlize-message` (`data-pos`, `data-status="sent|sending|failed"`)
 - `.channlize-message-user`
 - `.channlize-message-agent`
 - `.channlize-chat-input-container`
@@ -417,6 +499,15 @@ All components accept a `styles` prop for custom styling. You can also use CSS c
 
 This package is written in TypeScript and includes full type definitions. All components, hooks, and utilities are fully typed.
 
+## Documentation
+
+- Guide: https://channlize.com/docs/react
+- All docs: https://channlize.com/docs (quick start, API keys, troubleshooting)
+
+## Changelog
+
+[CHANGELOG.md](./CHANGELOG.md) lists every release of `@channlize/react`. Product updates: https://channlize.com/docs/changelog
+
 ## License
 
 MIT