@xhub-short/sdk 0.1.0-beta.0 → 0.1.0-beta.10

package/README.md

@@ -257,9 +257,24 @@ SDK đảm bảo hoạt động với Server-Side Rendering:
 ├── @xhub-short/contracts  (types, interfaces)
 ├── @xhub-short/core       (domain logic)
 ├── @xhub-short/adapters   (mock + preset adapters)
-└── react (peer dependency)
+├── @xhub-short/ui         (headless components)
+├── react (peer dependency)
+└── zustand (peer dependency)
 ```
 
+### Host App Installation
+
+```bash
+npm install @xhub-short/sdk
+```
+
+**That's it!** No other dependencies needed.
+
+**Bundled internally:**
+- `zustand` - state management (bundled in @xhub-short/core)
+- `clsx` - class names utility (bundled in @xhub-short/ui)
+- Custom `useTouchDrag` hook - gesture handling (bundled in @xhub-short/sdk)
+
 ---
 
 ## ✨ Chức năng chính
@@ -483,38 +498,88 @@ export type { FeedState, PlayerState, ResourceState, ... } from '@xhub-short/cor
 
 ## 🚀 Quick Start
 
-### Basic Usage
+### Simplest Usage (Recommended)
 
 ```tsx
-import { ShortVideoProvider, useFeed, usePlayer } from '@xhub-short/sdk';
+import { ShortVideoRoot, VideoFeed, DefaultSlot } from '@xhub-short/sdk';
 
 function App() {
   return (
-    <ShortVideoProvider
+    <ShortVideoRoot
       config={{
         preset: {
           baseUrl: 'https://api.example.com/v1',
           auth: { getAccessToken: () => localStorage.getItem('token') },
           endpoints: {
             feed: { list: '/videos', detail: '/videos/:id' },
-            interaction: { like: '/videos/:id/like', ... },
+            interaction: { like: '/videos/:id/like' },
           },
         },
       }}
+      errorMode="auto-skip-with-toast"
     >
-      <VideoFeed />
-    </ShortVideoProvider>
+      <VideoFeed renderSlot={(video, index) => (
+        <DefaultSlot 
+          video={video} 
+          index={index}
+          showBookmark={true}
+          onOpenComments={(videoId) => openSheet(videoId)}
+          onShare={(video) => shareVideo(video)}
+        />
+      )} />
+    </ShortVideoRoot>
   );
 }
-
-function VideoFeed() {
-  const { videos, loadInitial, loadMore, hasMore } = useFeed();
-  const { load, play, pause, isPlaying } = usePlayer();
-  
-  // Your UI here...
-}
 ```
 
+**That's it!** The SDK handles everything: video loading, HLS playback, swipe navigation, like/follow actions, error handling, and more.
+
+### DefaultSlot Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `video` | `VideoItem` | required | Video data |
+| `index` | `number` | required | Index in feed |
+| `showPoster` | `boolean` | `true` | Show poster |
+| `showLikeAnimation` | `boolean` | `true` | Double-tap hearts |
+| `showAuthorInfo` | `boolean` | `true` | Avatar + follow |
+| `showActionBar` | `boolean` | `true` | Like, comment, share |
+| `showVideoInfo` | `boolean` | `true` | Caption, hashtags |
+| `showProgressBar` | `boolean` | `true` | Progress bar |
+| `showBookmark` | `boolean` | `false` | Bookmark button |
+| `onOpenComments` | `(videoId) => void` | - | Comment click |
+| `onShare` | `(video) => void` | - | Share click |
+| `onOpenProfile` | `(author) => void` | - | Author click |
+| `onHashtagClick` | `(tag) => void` | - | Hashtag click |
+
+### Custom Usage (Advanced)
+
+For full control, use individual components:
+
+```tsx
+import { 
+  ShortVideoRoot, VideoFeed, VideoSlot, VideoPlayer,
+  ActionBar, AuthorInfo, VideoInfo, ProgressBar 
+} from '@xhub-short/sdk';
+import { VideoSlotOverlay, VideoSlotPoster } from '@xhub-short/ui';
+
+<VideoFeed renderSlot={(video, index) => (
+  <VideoSlot video={video} index={index}>
+    <VideoPlayer />
+    <VideoSlotPoster />
+    <VideoSlotOverlay>
+      <VideoSlotOverlay.Actions>
+        <AuthorInfo video={video} variant="avatar-badge" />
+        <ActionBar video={video} />
+      </VideoSlotOverlay.Actions>
+      <VideoSlotOverlay.Bottom>
+        <VideoInfo video={video} />
+        <ProgressBar showTime />
+      </VideoSlotOverlay.Bottom>
+    </VideoSlotOverlay>
+  </VideoSlot>
+)} />
+
 ### With Custom Adapters
 
 ```tsx
@@ -532,6 +597,75 @@ function VideoFeed() {
 
 ---
 
+## 👤 Guest Mode (Chế độ khách)
+
+SDK hỗ trợ chế độ khách cho phép người dùng chưa đăng nhập xem video và bình luận (read-only). Các tương tác (Like, Comment, Follow) sẽ bị chặn và trigger callback để Host App xử lý (ví dụ: hiện modal đăng nhập).
+
+### Cấu hình
+
+```tsx
+<ShortVideoRoot
+  config={{
+    // ...
+    guest: {
+      /**
+       * 'auto': Tự động detect dựa trên auth token (default)
+       * true: Force guest mode
+       * false: Disable guest mode
+       */
+      mode: 'auto',
+
+      /**
+       * Callback khi guest thực hiện hành động cần auth (Like, Comment, Follow...)
+       */
+      onAction: (action, context) => {
+        console.log('Guest Action:', action, context); 
+        // VD: showLoginModal();
+      }
+    }
+  }}
+>
+  <VideoFeed />
+</ShortVideoRoot>
+```
+
+### Các hành động được chặn
+- **Like / Bookmark**: Trigger `onAction`
+- **Follow**: Trigger `onAction`
+- **Comment Input**: Hiển thị nút "Login to comment". Khi click triggers `onAction` (`action='comment'`).
+
+---
+
+## ⚡ Prefetch Data (Tải trước dữ liệu)
+
+Cho phép Host App tải trước dữ liệu Feed (Reels) để trải nghiệm hiển thị tức thì (instant loading).
+
+### Cách sử dụng
+
+Gọi hàm `prefetchFeed` trước khi mount SDK components (ví dụ: khi hover vào menu Reels hoặc trong route loader).
+
+```tsx
+import { prefetchFeed } from '@xhub-short/sdk';
+
+// 1. Prefetch data (lưu vào bộ nhớ tạm)
+// Có thể gọi ở bất kỳ đâu trong Host App
+await prefetchFeed(sdkConfig, { ttl: 5 * 60 * 1000 });
+
+// ... Sau đó ...
+
+// 2. Khi User vào trang Reels, SDK sẽ tự động dùng data đã fetch
+<ShortVideoRoot config={sdkConfig}>
+  <VideoFeed />
+</ShortVideoRoot>
+```
+
+### Đặc điểm
+- **In-Memory Cache**: Dữ liệu chỉ lưu tạm trong RAM, mất khi refresh trang (đảm bảo fresh data).
+- **Auto-Consume**: `ShortVideoRoot` tự động tiêu thụ cache và xóa sau khi dùng.
+- **Performance**: Giúp giảm thời gian chờ đợi (LCP) xuống gần bằng 0 khi user chuyển trang.
+
+---
+
 ## 🔗 Liên kết với các Packages
 
 | Package | Quan hệ với SDK |