@taskon/widget-react 0.0.1 → 0.0.2

package/README.md

@@ -23,7 +23,7 @@ import { QuestWidget } from "@taskon/widget-react/quest";
 const App = () => (
   <TaskOnProvider
     config={{
-      apiKey: "your-api-key",
+      clientId: "your-client-id",
     }}
   >
     <YourApp />
@@ -43,6 +43,7 @@ import { TaskOnProvider, ThemeProvider, useTaskOnAuth } from "@taskon/widget-rea
 import { QuestWidget } from "@taskon/widget-react/quest";           // ~26KB CSS
 import { CommunityTaskList } from "@taskon/widget-react/community-task"; // ~51KB CSS
 import { LeaderboardWidget } from "@taskon/widget-react/leaderboard";   // ~17KB CSS
+import { UserCenterWidget } from "@taskon/widget-react/user-center";    // UserCenter CSS only
 ```
 
 ### Alternative: Main Entry Import (Loads All CSS)
@@ -61,7 +62,7 @@ import { QuestWidget } from "@taskon/widget-react/quest";
 const App = () => (
   <TaskOnProvider
     config={{
-      apiKey: "your-api-key",
+      clientId: "your-client-id",
     }}
   >
     <YourApp />
@@ -92,7 +93,7 @@ const YourApp = () => {
     <div>
       {userId && <p>TaskOn User ID: {userId}</p>}
       {/* Theme configured in TaskOn Dashboard */}
-      <QuestWidget configId="cfg_abc123" />
+      <QuestWidget widgetId={123} />
     </div>
   );
 };
@@ -102,17 +103,17 @@ const YourApp = () => {
 
 ```
 ┌─ TaskOnProvider ─────────────────────────────────────────┐
-│  config: { apiKey }                                      │
+│  config: { clientId }                                      │
 │  Purpose: Authentication only                            │
 │                                                          │
 │  ┌─ Mode A: Cloud Config ──────────────────────────────┐ │
-│  │  <QuestWidget configId="cfg_abc123" />              │ │
+│  │  <QuestWidget widgetId={123} />                     │ │
 │  │  → Theme from TaskOn cloud                          │ │
 │  └─────────────────────────────────────────────────────┘ │
 │                                                          │
 │  ┌─ Mode B: Local Theme ───────────────────────────────┐ │
 │  │  <ThemeProvider theme={{ mode: 'dark' }}>           │ │
-│  │    <QuestWidget />  /* no configId */               │ │
+│  │    <QuestWidget />  /* no widgetId */               │ │
 │  │  </ThemeProvider>                                   │ │
 │  └─────────────────────────────────────────────────────┘ │
 └──────────────────────────────────────────────────────────┘
@@ -122,17 +123,17 @@ const YourApp = () => {
 
 | Mode                  | Theme Source                         |
 | --------------------- | ------------------------------------ |
-| `configId` provided | Cloud config (ThemeProvider ignored) |
-| No `configId`       | ThemeProvider or default theme       |
+| `widgetId` provided | Cloud config (ThemeProvider ignored) |
+| No `widgetId`       | ThemeProvider or default theme       |
 
 ## Security
 
-TaskOn uses **API Key** authentication to verify that widget requests come from authorized projects.
+TaskOn uses **Client ID** authentication to verify that widget requests come from authorized projects.
 
-### Step 1: Get API Key from TaskOn Dashboard
+### Step 1: Get Client ID from TaskOn Dashboard
 
 ```
-API Key:  /KDiqEFNCaGTVTdTpCFrZOsUj5vDi5uGLSFmwyHeboE=  (for X-API-Key header)
+Client ID:  /KDiqEFNCaGTVTdTpCFrZOsUj5vDi5uGLSFmwyHeboE=  (for X-API-Key header)
 ```
 
 ### Step 2: Configure TaskOnProvider
@@ -140,7 +141,7 @@ API Key:  /KDiqEFNCaGTVTdTpCFrZOsUj5vDi5uGLSFmwyHeboE=  (for X-API-Key header)
 ```tsx
 <TaskOnProvider
   config={{
-    apiKey: "your-api-key",
+    clientId: "your-client-id",
   }}
 >
   <YourApp />
@@ -152,13 +153,13 @@ API Key:  /KDiqEFNCaGTVTdTpCFrZOsUj5vDi5uGLSFmwyHeboE=  (for X-API-Key header)
 All API requests include:
 
 ```
-X-API-Key: your-api-key        # Project authorization
+X-API-Key: your-client-id        # Project authorization
 Authorization: Bearer xxx       # User authorization (after login)
 ```
 
 ### Security Best Practices
 
-1. **Keep API Key secure** - Don't expose in public repositories
+1. **Keep Client ID secure** - Don't expose in public repositories
 2. **Use HTTPS** - All communication must be encrypted
 
 ## TaskOnProvider
@@ -176,8 +177,8 @@ The root provider component for authentication. Must wrap your application.
 
 ```typescript
 interface TaskOnProviderConfig {
-  // Required: API Key for authentication (X-API-Key header)
-  apiKey: string;
+  // Required: Client ID for authentication (X-API-Key header)
+  clientId: string;
 
   // Locale setting
   locale?: "en" | "ko" | "ja" | "ru" | "es"; // default: auto-detect
@@ -186,10 +187,13 @@ interface TaskOnProviderConfig {
   walletConfig?: {
     evmAdapter?: WalletAdapter; // Custom EVM wallet adapter
     solanaAdapter?: WalletAdapter; // Custom Solana wallet adapter
-    disableAutoDetect?: boolean; // Disable auto-detection
   };
 
-  // WalletConnect Project ID (required for WalletConnect support)
+  // WalletConnect Project ID
+  // Only needed when you design Web3 wallet login or wallet-based rewards
+  // (wallet binding, on-chain verification, NFT/token claiming, etc.)
+  // Optional; SDK has a built-in default project ID
+  // For production, strongly recommended to use your own project ID
   // Get your project ID at https://cloud.walletconnect.com
   walletConnectProjectId?: string;
 
@@ -215,7 +219,7 @@ interface TaskOnProviderConfig {
 ```tsx
 <TaskOnProvider
   config={{
-    apiKey: "your-api-key",
+    clientId: "your-client-id",
     locale: "ko",
   }}
 >
@@ -232,13 +236,13 @@ const App = () => {
   const [locale, setLocale] = useState("en");
 
   return (
-    <TaskOnProvider config={{ apiKey: "your-api-key", locale }}>
+    <TaskOnProvider config={{ clientId: "your-client-id", locale }}>
       <select value={locale} onChange={(e) => setLocale(e.target.value)}>
         <option value="en">English</option>
         <option value="ko">한국어</option>
         <option value="ja">日本語</option>
       </select>
-      <QuestWidget configId="cfg_abc123" />
+      <QuestWidget widgetId={123} />
     </TaskOnProvider>
   );
 };
@@ -265,7 +269,10 @@ Optional provider for theme configuration. Supports nesting for different theme
 ```typescript
 interface TaskOnThemeConfig {
   // Theme mode
-  mode?: "light" | "dark" | "auto"; // default: 'light'
+  mode?: "light" | "dark" | "auto"; // default: 'dark'
+
+  // Theme mode strategy (mainly for cloud dual mode)
+  modeStrategy?: "auto" | "toggle"; // default: 'auto'
 
   // Compact mode
   compact?: boolean; // default: false
@@ -315,6 +322,8 @@ interface MapToken {
   colorTextSecondary?: string;
   colorTextTertiary?: string;
   colorTextDisabled?: string;
+  colorLink?: string;
+  colorTextOnPrimary?: string;
 
   // Border
   colorBorder?: string;
@@ -340,6 +349,28 @@ interface MapToken {
 }
 ```
 
+### themeMode Override
+
+SDK can control theme mode per widget using `themeMode`:
+
+```tsx
+<QuestWidget widgetId={123} themeMode="light" />
+<QuestWidget widgetId={123} themeMode="dark" />
+<QuestWidget widgetId={123} themeMode="auto" />
+```
+
+`themeMode` is supported by:
+
+- `QuestWidget`
+- `CommunityTaskList`
+- `LeaderboardWidget`
+- `UserCenterWidget`
+
+Priority rule:
+
+- `themeMode` (widget prop) has the highest priority when provided.
+- Recommended usage: `dual + toggle` in B-end for clearer mode ownership.
+
 ### Token Priority
 
 ```
@@ -351,7 +382,7 @@ light/dark.map > light/dark.seed (derived) > map > seed (derived) > default
 Nested ThemeProviders inherit from parent and can override specific values:
 
 ```tsx
-<TaskOnProvider config={{ apiKey: "your-api-key" }}>
+<TaskOnProvider config={{ clientId: "your-client-id" }}>
   <ThemeProvider theme={{ mode: "light", seed: { colorPrimary: "#6366f1" } }}>
     <Header /> {/* light + primary #6366f1 */}
     <ThemeProvider theme={{ mode: "dark" }}>
@@ -416,19 +447,23 @@ Use `inherit={false}` for completely independent themes:
 
 ### Cloud Configuration
 
-Widgets support cloud configuration via `configId`. Configure in TaskOn Dashboard and load at runtime:
+Widgets support cloud configuration via `widgetId`. Configure in TaskOn Dashboard and load at runtime:
 
 ```tsx
 // Cloud config includes: theme, feature flags, custom texts
-<QuestWidget configId="cfg_abc123" />
+<QuestWidget widgetId={123} />
 ```
 
 ### Widget Props
 
 ```typescript
 interface WidgetProps {
-  // Cloud config ID from TaskOn Dashboard
-  configId?: string;
+  // Cloud widget ID from TaskOn Dashboard
+  widgetId?: number;
+
+  // Manual theme mode override (highest priority when provided)
+  // Recommended usage: pair with cloud dual+toggle for clearer ownership
+  themeMode?: "light" | "dark" | "auto";
 
   // Custom class names for widget parts
   classNames?: {
@@ -457,7 +492,7 @@ Widgets support fine-grained styling via `classNames` and `styles` props:
 ```tsx
 // Using classNames
 <QuestWidget
-  configId="cfg_abc123"
+  widgetId={123}
   classNames={{
     root: 'my-quest-widget',
     header: 'my-quest-header',
@@ -467,7 +502,7 @@ Widgets support fine-grained styling via `classNames` and `styles` props:
 
 // Using inline styles
 <QuestWidget
-  configId="cfg_abc123"
+  widgetId={123}
   styles={{
     root: { maxWidth: 400 },
     header: { borderBottom: '1px solid #eee' },
@@ -477,7 +512,7 @@ Widgets support fine-grained styling via `classNames` and `styles` props:
 
 // Combining both
 <QuestWidget
-  configId="cfg_abc123"
+  widgetId={123}
   classNames={{ root: 'custom-widget' }}
   styles={{ header: { backgroundColor: 'transparent' } }}
 />
@@ -489,13 +524,13 @@ Each widget documents its available parts in its own API reference.
 
 ```tsx
 // Example 1: Using cloud config (theme from Dashboard)
-<TaskOnProvider config={{ apiKey: 'your-api-key' }}>
-  <QuestWidget configId="cfg_abc123" />
-  <TaskWidget configId="cfg_xyz789" />
+<TaskOnProvider config={{ clientId: 'your-client-id' }}>
+  <QuestWidget widgetId={123} />
+  <TaskWidget widgetId={456} />
 </TaskOnProvider>
 
 // Example 2: Using local theme (no cloud config)
-<TaskOnProvider config={{ apiKey: 'your-api-key' }}>
+<TaskOnProvider config={{ clientId: 'your-client-id' }}>
   <ThemeProvider theme={{ mode: 'dark', seed: { colorPrimary: '#6366f1' } }}>
     <QuestWidget />
     <TaskWidget />
@@ -503,7 +538,7 @@ Each widget documents its available parts in its own API reference.
 </TaskOnProvider>
 
 // Example 3: Different local themes for different areas
-<TaskOnProvider config={{ apiKey: 'your-api-key' }}>
+<TaskOnProvider config={{ clientId: 'your-client-id' }}>
   <ThemeProvider theme={{ mode: 'light' }}>
     <TaskWidget />
   </ThemeProvider>
@@ -514,9 +549,9 @@ Each widget documents its available parts in its own API reference.
 </TaskOnProvider>
 
 // Example 4: Mixed - some with cloud config, some with local theme
-<TaskOnProvider config={{ apiKey: 'your-api-key' }}>
+<TaskOnProvider config={{ clientId: 'your-client-id' }}>
   {/* Cloud config */}
-  <QuestWidget configId="cfg_abc123" />
+  <QuestWidget widgetId={123} />
 
   {/* Local theme */}
   <ThemeProvider theme={{ mode: 'dark' }}>
@@ -594,34 +629,44 @@ TaskOn provides flexible wallet integration options:
 | Setup          | Behavior                              |
 | -------------- | ------------------------------------- |
 | Custom adapter | Uses your provided `WalletAdapter`  |
-| Default        | Uses built-in window.ethereum adapter |
+| Default        | Uses built-in wallet picker adapter |
 
 ### Custom Wallet Adapter (Recommended)
 
 If you want full control over wallet connection (e.g., using RainbowKit, Web3Modal), provide a custom adapter:
 
 ```tsx
+import { useMemo } from "react";
 import { createWalletAdapter } from "./my-wallet-adapter";
 
-<TaskOnProvider
-  config={{
-    apiKey: "your-api-key",
-    walletConfig: {
-      evmAdapter: createWalletAdapter(),
-    },
-  }}
->
-  <App />
-</TaskOnProvider>;
+const App = () => {
+  const evmAdapter = useMemo(() => createWalletAdapter(), []);
+
+  return (
+    <TaskOnProvider
+      config={{
+        clientId: "your-client-id",
+        walletConfig: {
+          evmAdapter,
+        },
+      }}
+    >
+      <MainContent />
+    </TaskOnProvider>
+  );
+};
 ```
 
+Note: keep `evmAdapter` reference stable (for example via `useMemo`) to avoid
+re-creating adapters and resetting wallet state on every render.
+
 ### Built-in Wallet Support
 
-If no custom adapter is provided, TaskOn automatically uses `window.ethereum` to connect to browser wallets like MetaMask:
+If no custom adapter is provided, TaskOn automatically uses built-in wallet picker flow:
 
 ```tsx
-// No wallet config needed - uses window.ethereum by default
-<TaskOnProvider config={{ apiKey: "your-api-key" }}>
+// No wallet config needed
+<TaskOnProvider config={{ clientId: "your-client-id" }}>
   <App />
 </TaskOnProvider>
 ```
@@ -632,23 +677,25 @@ When tasks require wallet binding (e.g., on-chain verification), TaskOn shows a
 
 **Desktop (without adapter):**
 - MetaMask
-- ONTO Wallet
 - Bitget Wallet
 - OKX Wallet
-- WalletConnect (requires `walletConnectProjectId`)
+- WalletConnect (uses SDK default project ID if not configured; not recommended for production)
 
 **Mobile (non-Dapp browser):**
-- WalletConnect only (requires `walletConnectProjectId`)
+- WalletConnect only (uses SDK default project ID if not configured; not recommended for production)
 
 **Mobile (Dapp browser / wallet app):**
 - Uses injected provider directly
 
+Only configure `walletConnectProjectId` when your product needs Web3 wallet login
+or wallet-based rewards (wallet binding, on-chain verification, NFT/token claiming).
+
 To enable WalletConnect in the dialog:
 
 ```tsx
 <TaskOnProvider
   config={{
-    apiKey: "your-api-key",
+    clientId: "your-client-id",
     walletConnectProjectId: "your-project-id", // Get from cloud.walletconnect.com
   }}
 >
@@ -658,10 +705,10 @@ To enable WalletConnect in the dialog:
 
 ### Built-in Wallet Management
 
-If no external provider is detected, the widget uses its built-in wallet management. No configuration needed:
+If no external adapter is provided, the widget uses built-in wallet management. No configuration needed:
 
 ```tsx
-<TaskOnProvider config={{ apiKey: "your-api-key" }}>
+<TaskOnProvider config={{ clientId: "your-client-id" }}>
   <App /> {/* Widget handles wallet connection internally */}
 </TaskOnProvider>
 ```
@@ -675,9 +722,6 @@ interface WalletConfig {
 
   // Solana wallet adapter (highest priority)
   solanaAdapter?: WalletAdapter;
-
-  // Disable auto-detection of external providers
-  disableAutoDetect?: boolean;
 }
 ```
 
@@ -716,7 +760,7 @@ const App = () => {
   return (
     <TaskOnProvider
       config={{
-        apiKey: "your-api-key",
+        clientId: "your-client-id",
         walletConfig: { evmAdapter },
       }}
     >
@@ -731,7 +775,7 @@ const App = () => {
 When multiple options are available:
 
 1. **Custom Adapter** - `walletConfig.evmAdapter` / `solanaAdapter` (highest)
-2. **Built-in Adapter** - window.ethereum adapter for EVM wallets (lowest)
+2. **Built-in Adapter** - SDK wallet picker adapter for EVM wallets (fallback)
 
 ## Hooks
 
@@ -1036,6 +1080,7 @@ Works with:
 
 ### Optional Peer Dependencies
 
+Install these only when you need Web3 wallet login or wallet-based reward flows.
 For WalletConnect support in the built-in wallet binding dialog:
 
 ```bash
@@ -1047,7 +1092,7 @@ Then configure your project ID:
 ```tsx
 <TaskOnProvider
   config={{
-    apiKey: "your-api-key",
+    clientId: "your-client-id",
     walletConnectProjectId: "your-walletconnect-project-id",
   }}
 >
@@ -1057,7 +1102,16 @@ Then configure your project ID:
 
 Get your WalletConnect Project ID at https://cloud.walletconnect.com
 
-If not configured, the WalletConnect option will be disabled in the wallet binding dialog.
+If not configured, the SDK will use a built-in default WalletConnect project ID.  
+For production use, strongly recommend configuring your own `walletConnectProjectId`.
+
+## Limitations
+
+- Quest Widget does not support opening pre-task targets from `CommunityPreTask` eligibility.
+  - In eligibility rows, pre-task names are displayed as plain text (non-clickable).
+  - Community names are hidden for `CommunityPreTask`, `CommunityUserPoints`, and `CommunityUserLevel` rows.
+  - `DiscordRole` keeps original `in {community}` display and uses `server_url` as link when available.
+- CommunityTask eligibility `CommunityPreTask` supports clicking task names to switch task dialogs.
 
 ## License