@channlize/react 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
+import { ReactNode, CSSProperties } from 'react';
 import { ChannlizeConfig, ChannlizeClient, CreateContactResponse, ChannlizeError, ContactFormData, ChatMessage, ChatSession, TrackEventOptions } from '@channlize/core';
 export { AuthenticationError, ChannlizeConfig, ChannlizeError, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, EventSeverity, FileAttachment, RateLimitError, SendMessageResponse, TrackEventOptions, ValidationError } from '@channlize/core';
 
@@ -54,6 +54,11 @@ interface UseChatSessionReturn {
     sendMessage: (content: string, attachments?: File[]) => Promise<void>;
     startSession: () => Promise<void>;
     endSession: () => Promise<void>;
+    /**
+     * Reopen the real-time stream for the current session after it failed
+     * (`error.code === 'SSE_ERROR'`). Routine reconnects are automatic.
+     */
+    reconnect: () => void;
 }
 /**
  * Hook for managing chat sessions with real-time messaging
@@ -61,7 +66,10 @@ interface UseChatSessionReturn {
 declare function useChatSession(options?: UseChatSessionOptions): UseChatSessionReturn;
 
 /**
- * Returns a stable `track` function bound to the provider client for event tracking (browser / widget key).
+ * Returns a stable `track` function bound to the provider client for log
+ * tracking (browser / widget key; shown under Log tracking in the
+ * dashboard). To post a Slack message when something happens, use Events
+ * (`notify` from `@channlize/core`) on your server instead.
  */
 declare function useChannlizeAnalytics(): {
     track: (name: string, options?: TrackEventOptions) => Promise<{
@@ -70,48 +78,186 @@ declare function useChannlizeAnalytics(): {
     }>;
 };
 
+/** `auto` and `system` both follow `prefers-color-scheme`. */
+type ContactFormTheme = 'auto' | 'system' | 'light' | 'dark';
+/** Whether a built-in field is shown, and whether it must be filled in. */
+type ContactFieldMode = 'required' | 'optional' | 'hidden';
+interface ContactFormTopic {
+    /** Identifies the option, e.g. for `defaultValues.topic` from a URL */
+    value: string;
+    /**
+     * Shown in the select, sent as `customFields.topic`, and used as the
+     * subject when that is blank. Defaults to `value`.
+     */
+    label?: string;
+}
+/** The built-in fields' values (also what `defaultValues` takes). */
+interface ContactFormValues {
+    name: string;
+    email: string;
+    company: string;
+    subject: string;
+    topic: string;
+    message: string;
+}
+interface ContactFormCustomField {
+    name: string;
+    label: string;
+    type: 'text' | 'email' | 'textarea' | 'select';
+    required?: boolean;
+    options?: string[];
+    placeholder?: string;
+}
+/** Every user-facing string in the form, for copy changes or translation. */
+interface ContactFormLabels {
+    name: string;
+    email: string;
+    company: string;
+    subject: string;
+    topic: string;
+    message: string;
+    namePlaceholder: string;
+    emailPlaceholder: string;
+    companyPlaceholder: string;
+    subjectPlaceholder: string;
+    topicPlaceholder: string;
+    messagePlaceholder: string;
+    optional: string;
+    submit: string;
+    submitting: string;
+    successTitle: string;
+    successMessage: string;
+    sendAnother: string;
+    /** Shown under a required field left empty */
+    errorRequired: string;
+    /** Shown under a required select left on the placeholder */
+    errorSelect: string;
+    errorEmail: string;
+    /** `{min}` is replaced with the minimum length */
+    errorTooShort: string;
+    /** `{max}` is replaced with the maximum length */
+    errorTooLong: string;
+    /** Announced when a submit is blocked by invalid fields */
+    errorSummary: string;
+    /** Shown when sending fails */
+    errorGeneric: string;
+    /** Shown when the API rate limit is hit */
+    errorRateLimit: string;
+    /** Small print under the submit button; '' hides it */
+    footnote: string;
+}
+declare const defaultContactFormLabels: ContactFormLabels;
 interface FormProps {
-    /** Custom fields to include in the form */
-    customFields?: Array<{
-        name: string;
-        label: string;
-        type: 'text' | 'email' | 'textarea' | 'select';
-        required?: boolean;
-        options?: string[];
-    }>;
+    /** Custom fields to include in the form (sent as `customFields`) */
+    customFields?: ContactFormCustomField[];
     /** Callback when form is successfully submitted */
-    onSuccess?: () => void;
+    onSuccess?: (response: CreateContactResponse) => void;
     /** Callback when form submission fails */
     onError?: (error: Error) => void;
     /** Custom CSS classes */
     className?: string;
-    /** Custom styles for form elements */
+    /** Custom styles for form elements (applied inline, so they win over the theme) */
     styles?: {
-        form?: React.CSSProperties;
-        field?: React.CSSProperties;
-        label?: React.CSSProperties;
-        input?: React.CSSProperties;
-        textarea?: React.CSSProperties;
-        button?: React.CSSProperties;
-        error?: React.CSSProperties;
-        success?: React.CSSProperties;
+        form?: CSSProperties;
+        field?: CSSProperties;
+        label?: CSSProperties;
+        input?: CSSProperties;
+        textarea?: CSSProperties;
+        button?: CSSProperties;
+        error?: CSSProperties;
+        success?: CSSProperties;
     };
-    /** Button text */
+    /** Button text (same as `labels.submit`) */
     submitText?: string;
-    /** Success message */
+    /** Success message (same as `labels.successMessage`) */
     successMessage?: string;
+    /** Colour scheme (default `light`). `auto` / `system` follow `prefers-color-scheme`. */
+    theme?: ContactFormTheme;
+    /** Accent colour (button, focus ring). Hex recommended. */
+    primaryColor?: string;
+    /** Text colour on the accent colour. Defaults to white or near-black, whichever is readable. */
+    primaryTextColor?: string;
+    /** `card` (default) draws a themed surface with padding; `plain` inherits the host's. */
+    variant?: 'card' | 'plain';
+    /** Skip the built-in stylesheet entirely (class names stay for your own CSS) */
+    unstyled?: boolean;
+    /**
+     * Built-in fields. Email and message are always required.
+     * Defaults: name `required`, subject `optional`, company `hidden`,
+     * topic `optional` when `topics` is set.
+     */
+    fields?: {
+        name?: ContactFieldMode;
+        company?: ContactFieldMode;
+        subject?: ContactFieldMode;
+        topic?: ContactFieldMode;
+    };
+    /** Options of the topic select; it is shown only when this is set */
+    topics?: Array<string | ContactFormTopic>;
+    /**
+     * Initial values, e.g. a topic from the URL (`?topic=sales`). A topic
+     * matches an option's value or label, case-insensitively.
+     */
+    defaultValues?: Partial<ContactFormValues>;
+    /** Override any user-facing string */
+    labels?: Partial<ContactFormLabels>;
+    /** Minimum message length (default `10`, what the Channlize API accepts) */
+    minMessageLength?: number;
+    /** Maximum message length (default `5000`) */
+    maxMessageLength?: number;
+    /** Add a hidden honeypot field; bots that fill it get a fake success (default `true`) */
+    honeypot?: boolean;
+    /** Show the built-in success state after sending (default `true`) */
+    showSuccessState?: boolean;
+    /** Prefix of the fields' ids (default `channlize`, e.g. `channlize-email`) */
+    idPrefix?: string;
 }
 
 /**
- * ContactForm component - Alias for Form component
- * Provides a form for collecting contact information and messages
+ * ContactForm component
+ *
+ * A themed, accessible contact form that posts to Channlize (and from there
+ * to your Slack). Inline validation, loading / success / error states, an
+ * optional topic select and company field, and a honeypot spam guard.
+ * Must be rendered inside `<ChannlizeProvider>`.
  */
 declare function ContactForm(props: FormProps): react.JSX.Element;
+type ContactFormProps = FormProps;
 
+type ChatTheme = 'auto' | 'light' | 'dark';
+/** Every user-facing string in the chat, for copy changes or translation. */
+interface SupportChatLabels {
+    online: string;
+    connecting: string;
+    reconnecting: string;
+    offline: string;
+    connectionLost: string;
+    startFailed: string;
+    retry: string;
+    today: string;
+    yesterday: string;
+    you: string;
+    sending: string;
+    failed: string;
+    remove: string;
+    moreOptions: string;
+    minimize: string;
+    endChat: string;
+    endChatTitle: string;
+    endChatDescription: string;
+    endChatConfirm: string;
+    cancel: string;
+    attach: string;
+    removeAttachment: string;
+    messages: string;
+    conversationEnded: string;
+    charactersLeft: string;
+}
+declare const defaultSupportChatLabels: SupportChatLabels;
 interface SupportChatProps extends UseChatSessionOptions {
     /** Custom CSS classes */
     className?: string;
-    /** Custom styles for chat elements */
+    /** Custom styles for chat elements (applied inline, so they win over the theme) */
     styles?: {
         container?: React.CSSProperties;
         header?: React.CSSProperties;
@@ -127,20 +273,48 @@ interface SupportChatProps extends UseChatSessionOptions {
     };
     /** Placeholder text for message input */
     placeholder?: string;
-    /** Header title */
+    /** Header title: your team or brand name */
     title?: string;
-    /** Button text */
+    /** Accessible label (and tooltip) of the send button */
     sendButtonText?: string;
     /** Show timestamps on messages */
     showTimestamps?: boolean;
     /** Allow file attachments */
     allowAttachments?: boolean;
+    /** Logo or team avatar URL, shown in the header and on the welcome screen */
+    avatarUrl?: string;
+    /** Custom avatar element (overrides `avatarUrl`) */
+    avatar?: ReactNode;
+    /** Text after "Online" in the header, e.g. "Replies in a few minutes". Set to '' to hide. */
+    statusText?: string;
+    /** Welcome heading shown before the first message */
+    greeting?: string;
+    /** Welcome text shown under the greeting */
+    welcomeMessage?: string;
+    /** Quick replies shown on the welcome screen; clicking one sends it */
+    suggestions?: string[];
+    /** Colour scheme. `auto` follows `prefers-color-scheme`. */
+    theme?: ChatTheme;
+    /** Accent colour (header, customer bubbles, send button). Hex recommended. */
+    primaryColor?: string;
+    /** Text colour on the accent colour. Defaults to white or near-black, whichever is readable. */
+    primaryTextColor?: string;
+    /** Locale for dates and times (defaults to the browser locale) */
+    locale?: string;
+    /** Maximum message length */
+    maxLength?: number;
+    /** Show "End conversation" in the header menu */
+    allowEndChat?: boolean;
+    /** When set, a minimize button is shown in the header and Esc calls it */
+    onMinimize?: () => void;
+    /** Override any user-facing string */
+    labels?: Partial<SupportChatLabels>;
 }
 /**
  * SupportChat component - Real-time chat interface
  * Provides a complete chat UI with message history and real-time updates
  */
-declare function SupportChat({ autoConnect, metadata, onMessage, onError, sessionId, persistSession, storageKey, className, styles, placeholder, title, sendButtonText, showTimestamps, allowAttachments, }: SupportChatProps): react.JSX.Element;
+declare function SupportChat({ autoConnect, metadata, onMessage, onError, sessionId, persistSession, storageKey, className, styles, placeholder, title, sendButtonText, showTimestamps, allowAttachments, avatarUrl, avatar, statusText, greeting, welcomeMessage, suggestions, theme, primaryColor, primaryTextColor, locale, maxLength, allowEndChat, onMinimize, labels: labelOverrides, }: SupportChatProps): react.JSX.Element;
 
 interface ChannlizeChatProps {
     /** Channlize configuration */
@@ -158,29 +332,36 @@ interface ChannlizeChatProps {
     buttonIcon?: ReactNode;
     /** Button size in pixels */
     buttonSize?: number;
-    /** Button colors */
+    /** Launcher colours. Default to `primaryColor`. */
     buttonColors?: {
         background?: string;
         hover?: string;
         text?: string;
     };
     /** Chat window props (passed to SupportChat) */
-    chatProps?: Omit<SupportChatProps, 'autoConnect'>;
+    chatProps?: Omit<SupportChatProps, 'autoConnect' | 'onMinimize'>;
+    /** Accent colour for the launcher and chat window (hex recommended) */
+    primaryColor?: string;
+    /** Colour scheme. `auto` (default) follows `prefers-color-scheme`. */
+    theme?: ChatTheme;
     /** Whether to start closed or open */
     defaultOpen?: boolean;
-    /** Whether to show badge with unread count */
+    /**
+     * Show `unreadCount` on the launcher instead of the built-in count. Without
+     * it, the launcher counts agent replies received while the chat is closed.
+     */
     showBadge?: boolean;
-    /** Unread count (for badge) */
+    /** Unread count (for badge, used with `showBadge`) */
     unreadCount?: number;
     /** Custom z-index */
     zIndex?: number;
-    /** Whether to show on mobile */
+    /** Whether to show the launcher on small screens (< 640px) */
     showOnMobile?: boolean;
     /** Callback when chat opens */
     onOpen?: () => void;
     /** Callback when chat closes */
     onClose?: () => void;
-    /** Whether to enable animations */
+    /** Whether to enable animations (always reduced with `prefers-reduced-motion`) */
     enableAnimations?: boolean;
     /** Custom class for button container */
     buttonClassName?: string;
@@ -201,13 +382,16 @@ interface ChannlizeChatProps {
  *     projectId: "your-project-id",
  *   }}
  *   position="bottom-right"
+ *   primaryColor="#2563eb"
  *   chatProps={{
- *     title: "Customer Support",
- *     placeholder: "How can we help?"
+ *     title: "Acme Support",
+ *     greeting: "Hi there!",
+ *     welcomeMessage: "Ask us anything.",
  *   }}
  * />
  * ```
  */
-declare function ChannlizeChat({ config, position, offset, buttonElement, buttonIcon, buttonSize, buttonColors, chatProps, defaultOpen, showBadge, unreadCount, zIndex, showOnMobile, onOpen, onClose, enableAnimations, buttonClassName, chatClassName, }: ChannlizeChatProps): react.JSX.Element | null;
+declare function ChannlizeChat({ config, position, offset, buttonElement, buttonIcon, buttonSize, buttonColors, chatProps, primaryColor, theme, defaultOpen, showBadge, unreadCount, zIndex, showOnMobile, onOpen, onClose, enableAnimations, buttonClassName, chatClassName, }: ChannlizeChatProps): react.JSX.Element | null;
 
-export { ChannlizeChat, ChannlizeProvider, ContactForm, SupportChat, useChannlize, useChannlizeAnalytics, useChatSession, useContactForm };
+export { ChannlizeChat, ChannlizeProvider, ContactForm, SupportChat, defaultContactFormLabels, defaultSupportChatLabels, useChannlize, useChannlizeAnalytics, useChatSession, useContactForm };
+export type { ChannlizeChatProps, ChatTheme, ContactFieldMode, ContactFormCustomField, ContactFormLabels, ContactFormProps, ContactFormTheme, ContactFormTopic, ContactFormValues, SupportChatLabels, SupportChatProps, UseChatSessionOptions, UseChatSessionReturn };