@xhub-reels/sdk 0.2.12 → 0.2.14

package/README.md

@@ -86,16 +86,53 @@ function MyFeed() {
 }
 ```
 
-## Thumbnail grid
+## Thumbnail grid → Modal
 
-`<ReelsFeedThumbnail>` is a headless grid component for the pre-drawer browsing UX
-(e.g. a community feed that opens the player drawer on tap). It must be mounted
-inside `<ReelsProvider>` and reads items from the same shared feed. The host
-provides card visuals via `renderThumbnail`.
+`<ReelsFeedThumbnail>` is a grid component for the pre-player browsing UX (e.g. a
+community feed that opens the player on tap). It must be mounted inside
+`<ReelsProvider>` and reads items from the same shared feed. The host provides
+card visuals via `renderThumbnail`.
+
+### SDK-owned modal (recommended)
+
+Pair `<ReelsFeedThumbnail openOnClick>` with `<ReelsModal>` to let the SDK own the
+open→play lifecycle end to end. This eliminates the "poster stuck for ~3s" stall:
+on tap, the SDK **mounts the feed offscreen-but-painted, prewarms the focused
+video and its neighbors synchronously, then slides the panel in** — so the first
+frame is already decoded by the time the animation finishes.
 
 ```tsx
-import { ReelsProvider, ReelsFeedThumbnail } from 'xhub-reels-sdk';
+import { ReelsProvider, ReelsFeedThumbnail, ReelsModal } from 'xhub-reels-sdk';
+
+function CommunityPage() {
+  return (
+    <ReelsProvider adapters={{ dataSource, interaction }}>
+      <ReelsFeedThumbnail
+        openOnClick
+        renderThumbnail={(item) => (
+          <article className="aspect-[3/2] rounded-lg overflow-hidden">
+            <img src={item.poster} alt="" />
+            <p>@{item.author.name}</p>
+          </article>
+        )}
+      />
+      <ReelsModal feedProps={{ renderOverlay, renderActions, initialMuted: false }} />
+    </ReelsProvider>
+  );
+}
+```
+
+`openOnClick` calls `navigation.open(index)` on tap; `<ReelsModal>` subscribes to
+the same navigation store and drives the rest. Because `play()` now starts inside
+the tap's transient-activation window, **`initialMuted={false}` unmuted autoplay
+is far more reliable** on mobile WebViews.
+
+### Headless callback (back-compat)
 
+The original headless approach still works — drive your own drawer/modal via
+`onThumbnailClick`:
+
+```tsx
 function CommunityPage() {
   const [drawerOpen, setDrawerOpen] = useState(false);
 
@@ -105,7 +142,6 @@ function CommunityPage() {
         renderThumbnail={(item) => (
           <article className="aspect-[3/2] rounded-lg overflow-hidden">
             <img src={item.poster} alt="" />
-            <p>@{item.author.name}</p>
           </article>
         )}
         onThumbnailClick={(id) => {
@@ -113,7 +149,7 @@ function CommunityPage() {
           window.history.replaceState(null, '', `#reel_uuid=${id}`);
         }}
       />
-      {drawerOpen && <ReelsDrawer onClose={() => setDrawerOpen(false)} />}
+      {drawerOpen && <YourDrawer onClose={() => setDrawerOpen(false)} />}
     </ReelsProvider>
   );
 }
@@ -124,21 +160,48 @@ By default, clicking a card calls `setFocusedIndexImmediate(index)` on the
 disable this glue (e.g. if the host manages focus separately), pass
 `setFocusOnClick={false}`.
 
-### Props
+### `<ReelsFeedThumbnail>` props
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `renderThumbnail` | `(item, index) => ReactNode` | required | Card visual for a single item |
-| `onThumbnailClick` | `(id, item, index) => void` | — | Click handler |
+| `openOnClick` | `boolean` | `false` | Open the SDK-owned `<ReelsModal>` via `navigation.open(index)` on tap |
+| `prewarmOnClick` | `boolean` | `true` | Fire HLS metadata prefetch on tap (mobile-friendly; runs even without hover) |
+| `onThumbnailClick` | `(id, item, index) => void` | — | Click handler (fires alongside `open` for back-compat) |
+| `setFocusOnClick` | `boolean` | `true` | Pre-focus the slot before `open`/`onThumbnailClick` fires |
+| `prefetchOnHover` | `boolean` | `false` | Opt-in HLS metadata prefetch on `pointerenter` |
 | `renderLoading` | `() => ReactNode` | — | Shown while loading with no items |
 | `renderEmpty` | `() => ReactNode` | — | Shown when feed is empty |
 | `renderError` | `({ message, retry }) => ReactNode` | — | Shown on error with no items |
 | `className` | `string` | `'grid grid-cols-2 gap-3'` | Outer wrapper className |
 | `wrap` | `boolean` | `true` | Set `false` to render without an outer `<div>` |
-| `setFocusOnClick` | `boolean` | `true` | Pre-focus the slot before `onThumbnailClick` fires |
-| `prefetchOnHover` | `boolean` | `false` | Opt-in HLS metadata prefetch on `pointerenter` |
 | `getKey` | `(item, index) => string` | `item.id` | Key override for duplicate lists |
 
+### `<ReelsModal>` props
+
+The modal is a **customizable shell**: the SDK owns timing and prewarm, while the
+host can override the animation and chrome. Omit any prop to fall back to a
+sensible default.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `feedProps` | `ReelsFeedProps` | — | Render props forwarded to the inner `<ReelsFeed>` (`renderOverlay`, `renderActions`, `initialMuted`, …) |
+| `animationConfig` | `{ duration?, easing?, direction? }` | `{ 300, cubic-bezier(0.22, 1, 0.36, 1), 'up' }` | Slide-in tuning; `direction` is `'up' \| 'down' \| 'fade'` |
+| `renderBackdrop` | `(state) => ReactNode` | dimmed overlay | Custom backdrop; `state` is `{ phase, openIndex, close }` |
+| `renderCloseButton` | `(state) => ReactNode` | default ✕ button | Custom close affordance |
+| `onOpen` | `(index) => void` | — | Fired when a modal session opens |
+| `onClose` | `() => void` | — | Fired when the modal fully closes |
+| `closeOnBackdropClick` | `boolean` | `true` | Close when the backdrop is clicked |
+| `closeOnEscape` | `boolean` | `true` | Close on the `Escape` key |
+| `lockBodyScroll` | `boolean` | `true` | Lock `<body>` scroll while open |
+| `prewarmForward` | `number` | `2` | How many forward neighbors to prewarm on open |
+| `className` | `string` | — | Class on the sliding panel |
+| `zIndex` | `number` | `1000` | Stacking context for the portal |
+| `portalTarget` | `HTMLElement \| null` | `document.body` | Portal mount node |
+
+`<ReelsModal>` honors `prefers-reduced-motion` (skips the slide), traps focus,
+restores focus to the trigger on close, and renders into a portal.
+
 ### Hover prefetch
 
 For hover-capable devices, opt into manifest prefetch so opening the player
@@ -150,7 +213,22 @@ feels instant:
 
 The SDK uses `adapters.videoLoader?.preloadMetadata?.(url)` and dedupes per item
 so a card only triggers one prefetch regardless of how many times it's hovered.
-Off by default to avoid surprising bandwidth on touch devices.
+On touch devices there's no hover, so prefer `prewarmOnClick` (on by default).
+
+### Migrating from the headless callback
+
+If you currently open your own drawer from `onThumbnailClick`:
+
+1. Add `openOnClick` to `<ReelsFeedThumbnail>` and mount `<ReelsModal>` as a
+   sibling inside `<ReelsProvider>`.
+2. Move your drawer's render props (`renderOverlay`, `renderActions`,
+   `initialMuted`, …) onto `<ReelsModal feedProps={{ … }}>`.
+3. Re-create your drawer's look with `animationConfig`, `renderBackdrop`, and
+   `renderCloseButton` — or drop them to use the defaults.
+4. Remove the host `drawerOpen` state and your `<ReelsDrawer>`/modal wrapper.
+
+`onThumbnailClick` still fires alongside `open`, so you can migrate
+incrementally (e.g. keep your URL-hash side effect) before deleting host state.
 
 ## Gesture Engine