npm package: @synapp/ui-kit
Description: SynApp UI Kit - Component library for building Mini Apps
Author: SynApp Team
Latest version: 1.1.0

# @synapp/ui-kit

The official UI component library and SDK for building SynApp Mini Apps.

## Installation

```bash
npm install @synapp/ui-kit
```

```bash
yarn add @synapp/ui-kit
```

### Basic Usage

```tsx
import { SynAppProvider, SynAppPage, SynAppButton } from '@synapp/ui';

function App() {
  return (
    <SynAppProvider requireAuth={true}>
      <SynAppPage title="My Mini App">
        <h1>Welcome to My Mini App!</h1>
        <SynAppButton variant="primary" onClick={() => alert('Hello!')}>
          Click Me
        </SynAppButton>
      </SynAppPage>
    </SynAppProvider>
  );
}

export default App;
```

## 📦 Components

### `<SynAppProvider>`

Root component that provides theme and authentication context.

**Props:**
- `children` (ReactNode) - Your app content
- `defaultTheme` (ThemeConfig) - Optional default theme
- `requireAuth` (boolean) - Whether auth is required globally
- `onSessionChange` (function) - Callback when session changes

**Example:**
```tsx
<SynAppProvider
  defaultTheme={{
    primaryColor: '#10B981',
    fontFamily: 'Inter',
  }}
  requireAuth={false}
  onSessionChange={(session) => console.log('Session:', session)}
>
  <App />
</SynAppProvider>
```

---

### `<SynAppPage>`

Page wrapper that handles loading and auth states automatically.

**Props:**
- `children` (ReactNode) - Page content
- `requireAuth` (boolean) - Whether this page requires login
- `loading` (ReactNode) - Custom loading component
- `unauthorized` (ReactNode) - Custom unauthorized component
- `title` (string) - Page title (sets document.title)
- `className` (string) - Additional CSS classes
- `style` (CSSProperties) - Inline styles

**Example:**
```tsx
<SynAppPage 
  requireAuth={true}
  title="Dashboard"
  loading={<CustomLoader />}
>
  <YourContent />
</SynAppPage>
```

---

### `<SynAppButton>`

Theme-aware button component that adapts to partner branding.

**Props:**
- `variant` ('primary' | 'secondary' | 'outline' | 'ghost') - Button style
- `size` ('sm' | 'md' | 'lg') - Button size
- `fullWidth` (boolean) - Full width button
- `loading` (boolean) - Show loading spinner
- `icon` (ReactNode) - Icon element
- `children` (ReactNode) - Button text
- All standard HTML button attributes

**Example:**
```tsx
<SynAppButton 
  variant="primary" 
  size="lg"
  loading={isLoading}
  onClick={handleSubmit}
>
  Submit
</SynAppButton>
```

---

## 🎨 Theming

### Automatic Theme Injection

When your Mini App runs inside SynApp, it automatically receives the partner's theme configuration:

```tsx
// CapCut's theme (injected automatically)
{
  primaryColor: '#000000',
  secondaryColor: '#FF6B6B',
  fontFamily: 'Helvetica Neue',
  borderRadius: '8px',
  darkMode: true
}

// Shopee's theme (injected automatically)
{
  primaryColor: '#EE4D2D',
  secondaryColor: '#F05D40',
  fontFamily: 'Roboto',
  borderRadius: '4px',
  darkMode: false
}
```

### Using Theme in Custom Components

```tsx
import { useTheme } from '@synapp/ui';

function CustomComponent() {
  const theme = useTheme();
  
  return (
    <div style={{ 
      backgroundColor: theme.primaryColor,
      fontFamily: theme.fontFamily 
    }}>
      Themed Content
    </div>
  );
}
```

---

## 🔐 Authentication

### Using Session Data

```tsx
import { useSession } from '@synapp/ui';

function UserProfile() {
  const { session, isLoading, isAuthenticated } = useSession();
  
  if (isLoading) return <p>Loading...</p>;
  if (!isAuthenticated) return <p>Please login</p>;
  
  return (
    <div>
      <h2>Welcome, {session.user.email}!</h2>
      <p>User ID: {session.user.id}</p>
    </div>
  );
}
```

### Manual Login/Logout

```tsx
import { useSynApp } from '@synapp/ui';

function AuthButtons() {
  const { isAuthenticated, login, logout } = useSynApp();
  
  return (
    <div>
      {isAuthenticated ? (
        <button onClick={logout}>Logout</button>
      ) : (
        <button onClick={login}>Login</button>
      )}
    </div>
  );
}
```

---

## 🎯 Complete Example

```tsx
import { 
  SynAppProvider, 
  SynAppPage, 
  SynAppButton,
  useSession,
  useTheme 
} from '@synapp/ui';

function Dashboard() {
  const { session } = useSession();
  const theme = useTheme();
  
  return (
    <div style={{ padding: '2rem' }}>
      <h1 style={{ color: theme.primaryColor }}>
        Welcome, {session?.user.email}!
      </h1>
      
      <SynAppButton variant="primary" size="lg">
        Get Started
      </SynAppButton>
      
      <SynAppButton variant="outline" size="md">
        Learn More
      </SynAppButton>
    </div>
  );
}

function App() {
  return (
    <SynAppProvider>
      <SynAppPage requireAuth={true} title="My Dashboard">
        <Dashboard />
      </SynAppPage>
    </SynAppProvider>
  );
}

export default App;
```

---

## 🛠️ TypeScript Support

Full TypeScript support with exported types:

```tsx
import type { 
  ThemeConfig, 
  UserSession, 
  SynAppButtonProps 
} from '@synapp/ui';

const customTheme: ThemeConfig = {
  primaryColor: '#6366F1',
  secondaryColor: '#8B5CF6',
};

const handleSession = (session: UserSession | null) => {
  if (session) {
    console.log('User logged in:', session.user.id);
  }
};
```

---

## 📚 API Reference

### Hooks

#### `useSynApp()`
Returns full context including theme, session, and auth methods.

```tsx
const { theme, session, isLoading, isAuthenticated, login, logout } = useSynApp();
```

#### `useTheme()`
Returns only theme configuration.

```tsx
const theme = useTheme();
```

#### `useSession()`
Returns only session-related data.

```tsx
const { session, isLoading, isAuthenticated } = useSession();
```

---

## 🎨 Theme Configuration

```typescript
interface ThemeConfig {
  primaryColor?: string;      // Main brand color
  secondaryColor?: string;    // Secondary brand color
  fontFamily?: string;        // Font family
  borderRadius?: string;      // Border radius (e.g., '8px')
  darkMode?: boolean;         // Dark mode enabled
}
```

---

## 🔒 Session Object

```typescript
interface UserSession {
  user: {
    id: string;
    email: string;
    user_metadata?: Record<string, any>;
  };
  access_token: string;
  refresh_token: string;
}
```

---

## 🚨 Error Handling

```tsx
import { SynAppProvider } from '@synapp/ui';

function App() {
  return (
    <SynAppProvider
      onSessionChange={(session) => {
        if (!session) {
          console.log('User logged out or session expired');
        }
      }}
    >
      <YourApp />
    </SynAppProvider>
  );
}
```

---

## 📦 Bundle Size

- **Minified**: ~8KB
- **Gzipped**: ~3KB

---

## 🤝 Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md).

---

## 📄 License

MIT © SynApp Team

---

## 🔗 Links

- [Documentation](https://docs.synapp.store)
- [Examples](https://github.com/synapp/examples)
- [Discord Community](https://discord.gg/synapp)

---

**Built with ❤️ by the SynApp Team**