@avatarfirst/react 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,430 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+import * as _avatarfirst_core from '@avatarfirst/core';
+import { AvatarAgent as AvatarAgent$1, AvatarState, OverlayInstance, OverlayConfig, AvatarEngineEvents, AvatarFirstClientConfig, MessageResponse, SessionResponse, OverlayAnimation } from '@avatarfirst/core';
+import { Variants } from 'framer-motion';
+import { ClassValue } from 'clsx';
+
+interface AvatarProviderProps {
+    /** AvatarAgent instance (from createAvatarAgent) */
+    agent: AvatarAgent$1;
+    /** Whether to auto-start the session on mount */
+    autoStart?: boolean;
+    children: ReactNode;
+}
+/** Provider that syncs AvatarAgent state to React context */
+declare function AvatarProvider({ agent, autoStart, children }: AvatarProviderProps): react_jsx_runtime.JSX.Element;
+
+/** Context value provided by AvatarProvider */
+interface AvatarContextValue {
+    /** The underlying AvatarAgent instance */
+    agent: AvatarAgent$1 | null;
+    /** Current avatar state */
+    state: AvatarState;
+    /** Whether the avatar is in an active state (connected, speaking, listening, thinking) */
+    isConnected: boolean;
+    /** Currently visible overlays */
+    overlays: OverlayInstance[];
+}
+declare const AvatarContext: React.Context<AvatarContextValue | null>;
+
+/** Hook to access avatar state and controls */
+declare function useAvatar(): {
+    agent: _avatarfirst_core.AvatarAgent | null;
+    state: _avatarfirst_core.AvatarState;
+    isConnected: boolean;
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+    speak: (text: string) => Promise<void>;
+    message: (text: string) => Promise<void>;
+    interrupt: () => Promise<void>;
+    startListening: () => void;
+    stopListening: () => void;
+    attachVideoElement: (el: HTMLVideoElement) => void;
+};
+
+/** Hook to manage overlays */
+declare function useOverlay(overlayId?: string): {
+    overlays: _avatarfirst_core.OverlayInstance[];
+    isVisible: boolean;
+    overlayData: _avatarfirst_core.OverlayInstance | undefined;
+    show: (config: OverlayConfig) => void;
+    hide: (id?: string) => void;
+};
+
+/** Hook to subscribe to engine events */
+declare function useAvatarEvent<K extends keyof AvatarEngineEvents>(event: K, handler: (data: AvatarEngineEvents[K]) => void): void;
+
+/** Hook to trigger and toggle actions */
+declare function useAction(): {
+    trigger: (actionId: string) => void;
+};
+
+interface UseAvatarFirstOptions extends AvatarFirstClientConfig {
+    onOverlay?: (overlay: MessageResponse['overlay']) => void;
+    onAction?: (action: {
+        type: string;
+        payload: Record<string, unknown>;
+    }) => void;
+    onStateChange?: (state: AvatarFirstState) => void;
+}
+type AvatarFirstState = 'idle' | 'connecting' | 'connected' | 'error';
+interface UseAvatarFirstReturn {
+    state: AvatarFirstState;
+    sessionId: string | null;
+    greeting: string | null;
+    avatarToken: SessionResponse['avatar'] | null;
+    overlays: MessageResponse['overlay'][];
+    isProcessing: boolean;
+    error: string | null;
+    connect: () => Promise<SessionResponse | null>;
+    sendMessage: (text: string) => Promise<MessageResponse | null>;
+    disconnect: () => void;
+}
+declare function useAvatarFirst(options: UseAvatarFirstOptions): UseAvatarFirstReturn;
+
+interface AvatarAgentProps {
+    /** AvatarAgent instance (from createAvatarAgent) */
+    config: AvatarAgent$1;
+    /** Map of overlay component names to React components */
+    overlayComponents?: Record<string, React__default.ComponentType<any>>;
+    /** Whether to auto-start the session */
+    autoStart?: boolean;
+    children: ReactNode;
+}
+/**
+ * Top-level convenience component that wraps AvatarProvider + OverlayContainer.
+ *
+ * Usage:
+ * ```tsx
+ * <AvatarAgent config={agent} overlayComponents={{ card: CardOverlay }}>
+ *   <AvatarView size="fullscreen" />
+ * </AvatarAgent>
+ * ```
+ */
+declare function AvatarAgent({ config, overlayComponents, autoStart, children, }: AvatarAgentProps): react_jsx_runtime.JSX.Element;
+
+interface AvatarFirstProps {
+    apiKey: string;
+    baseUrl?: string;
+    onOverlay?: (overlay: MessageResponse['overlay']) => void;
+    onAction?: (action: {
+        type: string;
+        payload: Record<string, unknown>;
+    }) => void;
+    onStateChange?: (state: string) => void;
+    className?: string;
+    overlayComponents?: Record<string, React__default.ComponentType<any>>;
+}
+/**
+ * All-in-one AvatarFirst component.
+ *
+ * Usage:
+ * ```tsx
+ * import { AvatarFirst } from '@avatarfirst/react'
+ *
+ * function App() {
+ *   return <AvatarFirst apiKey="af_live_abc123" />
+ * }
+ * ```
+ */
+declare function AvatarFirst({ apiKey, baseUrl, onOverlay, onAction, onStateChange, className, overlayComponents, }: AvatarFirstProps): react_jsx_runtime.JSX.Element;
+
+interface AvatarViewProps {
+    /** Display size */
+    size?: 'small' | 'medium' | 'large' | 'fullscreen' | 'hero';
+    /** Whether to show the state indicator badge */
+    showStatus?: boolean;
+    /** Additional CSS class */
+    className?: string;
+}
+/** Streaming avatar display component */
+declare function AvatarView({ size, showStatus, className }: AvatarViewProps): react_jsx_runtime.JSX.Element;
+
+interface AvatarFallbackProps {
+    state: AvatarState;
+    size: string;
+}
+/** Animated face component -- fallback when HeyGen is not connected */
+declare function AvatarFallback({ size, state }: AvatarFallbackProps): react_jsx_runtime.JSX.Element;
+
+interface OverlayContainerProps {
+    /** Map of component names to React components */
+    components: Record<string, React__default.ComponentType<any>>;
+}
+/** Renders all visible overlays with AnimatePresence */
+declare function OverlayContainer({ components }: OverlayContainerProps): react_jsx_runtime.JSX.Element;
+
+interface CardOverlayData {
+    title?: string;
+    description?: string;
+    items?: Array<{
+        label: string;
+        value?: string;
+        icon?: string;
+    }>;
+    actions?: Array<{
+        label: string;
+        onClick?: () => void;
+    }>;
+}
+interface CardOverlayProps {
+    data?: CardOverlayData;
+    overlayId: string;
+    onDismiss: () => void;
+}
+/** Data card overlay with title, items, and action buttons */
+declare function CardOverlay({ data, onDismiss }: CardOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface FormField {
+    name: string;
+    label: string;
+    type?: 'text' | 'email' | 'textarea' | 'select';
+    placeholder?: string;
+    options?: string[];
+    required?: boolean;
+}
+interface FormOverlayData {
+    title?: string;
+    fields?: FormField[];
+    submitLabel?: string;
+    onSubmit?: (values: Record<string, string>) => void;
+}
+interface FormOverlayProps {
+    data?: FormOverlayData;
+    overlayId: string;
+    onDismiss: () => void;
+}
+/** Dynamic form overlay */
+declare function FormOverlay({ data, onDismiss }: FormOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface TableOverlayData {
+    title?: string;
+    columns?: string[];
+    rows?: string[][];
+}
+interface TableOverlayProps {
+    data?: TableOverlayData;
+    overlayId: string;
+    onDismiss: () => void;
+}
+/** Tabular data overlay */
+declare function TableOverlay({ data, onDismiss }: TableOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface ProgressStep {
+    label: string;
+    completed: boolean;
+    active?: boolean;
+}
+interface ProgressOverlayData {
+    title?: string;
+    steps?: ProgressStep[];
+}
+interface ProgressOverlayProps {
+    data?: ProgressOverlayData;
+    overlayId: string;
+    onDismiss: () => void;
+}
+/** Step-by-step progress overlay */
+declare function ProgressOverlay({ data, onDismiss }: ProgressOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface ConfirmOverlayData {
+    title?: string;
+    message?: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    onConfirm?: () => void;
+    onCancel?: () => void;
+}
+interface ConfirmOverlayProps {
+    data?: ConfirmOverlayData;
+    overlayId: string;
+    onDismiss: () => void;
+}
+/** Yes/No confirmation overlay */
+declare function ConfirmOverlay({ data, onDismiss }: ConfirmOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface ChatMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    timestamp?: string;
+}
+interface ChatOverlayData {
+    title?: string;
+    messages?: ChatMessage[];
+    suggestions?: string[];
+}
+interface ChatOverlayProps {
+    data?: ChatOverlayData;
+    overlayId: string;
+    onDismiss: () => void;
+}
+/** Chat messages overlay (from CopilotWidget pattern) */
+declare function ChatOverlay({ data, onDismiss }: ChatOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface Insight {
+    type: 'recommendation' | 'comparison' | 'warning';
+    text: string;
+    confidence?: number;
+}
+interface InsightOverlayData {
+    title?: string;
+    subtitle?: string;
+    insights?: Insight[];
+    actions?: string[];
+    onAction?: (action: string) => void;
+}
+interface InsightOverlayProps {
+    data?: InsightOverlayData;
+    overlayId: string;
+    onDismiss: () => void;
+}
+/** AI insights overlay (from ShortlisterAgent pattern) */
+declare function InsightOverlay({ data, onDismiss }: InsightOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface DetailCardOverlayData {
+    title?: string;
+    body?: string;
+    image?: string;
+    metadata?: Record<string, string>;
+    actions?: Array<{
+        label: string;
+        onClick?: () => void;
+    }>;
+}
+interface DetailCardOverlayProps {
+    data?: DetailCardOverlayData;
+    overlayId: string;
+    onDismiss: () => void;
+}
+/** Detailed single-entity view with image, body text, metadata, and actions */
+declare function DetailCardOverlay({ data, onDismiss }: DetailCardOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface ComparisonItem {
+    name: string;
+    attributes: Record<string, string | number>;
+}
+interface ComparisonOverlayData {
+    title?: string;
+    items?: ComparisonItem[];
+}
+interface ComparisonOverlayProps {
+    data?: ComparisonOverlayData;
+    overlayId: string;
+    onDismiss: () => void;
+}
+/** Side-by-side comparison table for 2-4 items */
+declare function ComparisonOverlay({ data, onDismiss }: ComparisonOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface TimeSlot {
+    date: string;
+    time: string;
+    available?: boolean;
+}
+interface CalendarOverlayData {
+    title?: string;
+    available_slots?: TimeSlot[];
+    onSelect?: (slot: TimeSlot) => void;
+}
+interface CalendarOverlayProps {
+    data?: CalendarOverlayData;
+    overlayId: string;
+    onDismiss: () => void;
+}
+/** Date/time picker with available slots grouped by date */
+declare function CalendarOverlay({ data, onDismiss }: CalendarOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface MediaOverlayData {
+    title?: string;
+    url?: string;
+    type?: 'video' | 'audio' | 'image';
+    alt?: string;
+    autoplay?: boolean;
+}
+interface MediaOverlayProps {
+    data?: MediaOverlayData;
+    overlayId: string;
+    onDismiss: () => void;
+}
+/** Media player overlay for video, audio, or image content */
+declare function MediaOverlay({ data, onDismiss }: MediaOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface MapLocation {
+    lat: number;
+    lng: number;
+    label?: string;
+}
+interface MapOverlayData {
+    title?: string;
+    locations?: MapLocation[];
+}
+interface MapOverlayProps {
+    data?: MapOverlayData;
+    overlayId: string;
+    onDismiss: () => void;
+}
+/** Location display with map links */
+declare function MapOverlay({ data, onDismiss }: MapOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface RichTextOverlayData {
+    title?: string;
+    content?: string;
+}
+interface RichTextOverlayProps {
+    data?: RichTextOverlayData;
+    overlayId: string;
+    onDismiss: () => void;
+}
+/** Rich text / markdown display overlay */
+declare function RichTextOverlay({ data, onDismiss }: RichTextOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface ChartSeries {
+    label: string;
+    value: number;
+    color?: string;
+}
+interface ChartOverlayData {
+    title?: string;
+    type?: 'bar' | 'line' | 'pie';
+    series?: ChartSeries[];
+}
+interface ChartOverlayProps {
+    data?: ChartOverlayData;
+    overlayId: string;
+    onDismiss: () => void;
+}
+/** Chart overlay with bar, line, or pie visualization using pure SVG */
+declare function ChartOverlay({ data, onDismiss }: ChartOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface FileUploadOverlayData {
+    title?: string;
+    accept?: string[];
+    max_size?: number;
+    multiple?: boolean;
+    onUpload?: (files: File[]) => void;
+}
+interface FileUploadOverlayProps {
+    data?: FileUploadOverlayData;
+    overlayId: string;
+    onDismiss: () => void;
+}
+/** File upload overlay with drag-and-drop zone */
+declare function FileUploadOverlay({ data, onDismiss }: FileUploadOverlayProps): react_jsx_runtime.JSX.Element;
+
+declare const pageTransition: Variants;
+declare const fadeIn: Variants;
+declare const fadeInUp: Variants;
+declare const cardHover: Variants;
+declare const avatarPulse: Variants;
+declare const staggerContainer: Variants;
+declare const slideIn: Variants;
+declare const scaleIn: Variants;
+
+/** Map overlay animation names to framer-motion variants */
+declare function getOverlayVariants(animation?: OverlayAnimation): Variants;
+
+declare function cn(...inputs: ClassValue[]): string;
+
+export { AvatarAgent, AvatarContext, type AvatarContextValue, AvatarFallback, AvatarFirst, type AvatarFirstProps, type AvatarFirstState, AvatarProvider, AvatarView, CalendarOverlay, CardOverlay, ChartOverlay, ChatOverlay, ComparisonOverlay, ConfirmOverlay, DetailCardOverlay, FileUploadOverlay, FormOverlay, InsightOverlay, MapOverlay, MediaOverlay, OverlayContainer, ProgressOverlay, RichTextOverlay, TableOverlay, type UseAvatarFirstOptions, type UseAvatarFirstReturn, avatarPulse, cardHover, cn, fadeIn, fadeInUp, getOverlayVariants, pageTransition, scaleIn, slideIn, staggerContainer, useAction, useAvatar, useAvatarEvent, useAvatarFirst, useOverlay };