starchild-widget/README.md

Starchild Widget

# StarChild Widget

A powerful React Widget SDK with theme switching, internationalization, authentication management, and draggable floating components.

## 📦 Installation

### NPM Installation (Only Supported Method)

This widget only supports installation via npm package managers and is designed specifically for React projects:

```bash
# Using npm
npm install starchild-widget

# Using yarn
yarn add starchild-widget

# Using pnpm
pnpm add starchild-widget
```

> **Note**: This widget does not support CDN imports and must be used in React projects.

## 🚀 Quick Start

### React Hook Method (Recommended and Only Supported)

This widget **exposes APIs only through React Hooks**, providing automated lifecycle management and a clean functional interface.

#### Complete Configuration Example

```typescript
import { useStarChildWidget, ThemeMode, Locale, ComponentType } from 'starchild-widget'

function MyComponent() {
  const {
    init,
    isInitialized,
    setThemeMode,
    setLocale,
    setChatVisible,
    showChatModal,
    // ... more methods
  } = useStarChildWidget()

  React.useEffect(() => {
    init({
      // Theme configuration
      themeMode: ThemeMode.DARK, // ThemeMode.DARK | ThemeMode.LIGHT
      customTheme: {
        colors: {
          dn1: '#00d4ff',
          dn2: '#ff6b6b'
        }
      },
      
      // Language configuration
      locale: Locale.ZH_CN, // Locale.EN_US | Locale.ZH_CN
      
      // Environment configuration
      environment: 'testnet', // 'testnet' | 'mainnet'
      
      // Authentication configuration (Required)
      secretKey: 'your-secret-key',
      accountId: 'your-account-id',
      orderlyKey: 'your-orderly-key',
      aiChatKey: 'your-ai-chat-key',
      telegramUserId: 'your-telegram-user-id',
      
      // Component configuration
      components: {
        chat: {
          type: ComponentType.CHAT,
          visible: true,
          position: { x: 100, y: 100 },
          disabled: false
        },
        search: {
          type: ComponentType.SEARCH,
          visible: false,
          position: { x: 200, y: 100 },
          disabled: false
        }
      },
      
      // Global styles
      zIndex: 9999,
      globalCSS: 'your-custom-css',
      
      // Event callbacks
      onError: (error) => {
        console.error('Widget Error:', error)
      },
      onPositionChange: (position) => {
        console.log('Component position changed:', position)
      },
      onReady: () => {
        console.log('Widget Ready!')
      },
      onChatModalOpen: () => {
        console.log('Chat modal opened')
      },
      onChatModalClose: () => {
        console.log('Chat modal closed')
      }
    })
  }, [])

  return (
    <div>
      {/* Your application content */}
    </div>
  )
}
```

#### Configuration Options (WidgetConfig)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `themeMode` | `ThemeMode.LIGHT \| ThemeMode.DARK` | No | `ThemeMode.DARK` | Theme mode |
| `customTheme` | `Partial<Theme>` | No | - | Custom theme override |
| `locale` | `Locale.EN_US \| Locale.ZH_CN` | No | `Locale.EN_US` | Language setting |
| `environment` | `'testnet' \| 'mainnet'` | No | `'testnet'` | Environment configuration |
| `secretKey` | `string` | **Yes** | - | Secret Key for authentication |
| `accountId` | `string` | **Yes** | - | Account ID for authentication |
| `orderlyKey` | `string` | **Yes** | - | Orderly Key for authentication |
| `aiChatKey` | `string` | **Yes** | - | AI Chat API Key |
| `telegramUserId` | `string` | **Yes** | - | Telegram User ID |
| `components` | `ComponentConfig` | No | - | Component-specific configuration |
| `components.chat` | `ChatConfig` | No | `{type: ComponentType.CHAT, visible: true}` | Chat button configuration |
| `components.search` | `SearchConfig` | No | `{type: ComponentType.SEARCH, visible: false}` | Search input configuration |
| `zIndex` | `number` | No | `9999` | z-index level |
| `globalCSS` | `string` | No | - | Global CSS styles |
| `onError` | `(error: Error) => void` | No | - | Error callback |
| `onPositionChange` | `(position: Position) => void` | No | - | Position change callback |
| `onReady` | `() => void` | No | - | Ready callback |
| `onSearchOpen` | `() => void` | No | - | Search open callback |
| `onSearchClose` | `() => void` | No | - | Search close callback |
| `onChatModalOpen` | `() => void` | No | - | Chat modal open callback |
| `onChatModalClose` | `() => void` | No | - | Chat modal close callback |
| `onChatModalDockToEdge` | `(edge: string) => void` | No | - | Chat modal dock to edge callback |
| `onChatModalDetachFromEdge` | `() => void` | No | - | Chat modal detach from edge callback |

### Other Exported Methods

While using the Hook is recommended, the following methods can also be imported from the package:

```typescript
import { 
  StarChildWidget,  // Widget class (not recommended for direct use)
  init,             // Init function (not recommended for direct use)
  getInstance,      // Get instance function (not recommended for direct use)
  destroy,          // Destroy function (not recommended for direct use)
} from 'starchild-widget'

// Note: These methods are mainly for internal implementation, use useStarChildWidget Hook instead
```

> **Recommendation**: Always use the `useStarChildWidget` Hook, which provides better React integration and automatic lifecycle management.

---

Made with ❤️ by [StarChild Team](https://github.com/Starchild-ai-agent)