@xhub-reels/sdk 0.1.22 → 0.2.1

package/README.md

@@ -111,6 +111,48 @@ function SwipeableFeed() {
 }
 ```
 
+## Thumbnail grid
+
+Headless pre-drawer browsing UX. Mount inside `<ReelsProvider>`. Host provides the
+card visuals via `renderThumbnail`; the SDK ships no default card.
+
+```tsx
+import { ReelsFeedThumbnail } from 'xhub-reels-sdk';
+
+<ReelsFeedThumbnail
+  renderThumbnail={(videoData) => (
+    <article className="aspect-[3/2] rounded-lg overflow-hidden">
+      <img src={videoData.poster} alt="" />
+      <p>@{videoData.author.name}</p>
+    </article>
+  )}
+  onThumbnailClick={(id) => openDrawer(id)}
+/>
+```
+
+Opt-in hover prefetch (warms HLS manifest via `adapters.videoLoader.preloadMetadata`):
+
+```tsx
+<ReelsFeedThumbnail prefetchOnHover renderThumbnail={...} />
+```
+
+On click the SDK calls `ResourceGovernor.setFocusedIndexImmediate(index)` before
+invoking `onThumbnailClick`, so opening `<ReelsFeed>` lands on the tapped item
+without a scroll-to-index flash. Disable with `setFocusOnClick={false}`.
+
+Custom slots for the zero-items branches:
+
+```tsx
+<ReelsFeedThumbnail
+  renderThumbnail={(item) => <Card item={item} />}
+  renderLoading={() => <SkeletonGrid />}
+  renderEmpty={() => <EmptyState />}
+  renderError={({ message, retry }) => (
+    <ErrorBox message={message} onRetry={retry} />
+  )}
+/>
+```
+
 ## Architecture
 
 ```

package/dist/index.cjs

@@ -2499,6 +2499,88 @@ function parsePxTranslateY(el) {
   if (!match || !match[1]) return 0;
   return Number.parseFloat(match[1]);
 }
+var DEFAULT_CLASSNAME = "grid grid-cols-2 gap-3";
+var defaultGetKey = (item) => item.id;
+var buttonResetStyle = {
+  all: "unset",
+  display: "block",
+  cursor: "pointer",
+  width: "100%",
+  boxSizing: "border-box"
+};
+function ReelsFeedThumbnail({
+  renderThumbnail,
+  onThumbnailClick,
+  renderLoading,
+  renderEmpty,
+  renderError,
+  className = DEFAULT_CLASSNAME,
+  wrap = true,
+  setFocusOnClick = true,
+  prefetchOnHover = false,
+  getKey = defaultGetKey
+}) {
+  const { items, loading, error, refresh } = useFeed();
+  const { setFocusedIndexImmediate } = useResource();
+  const { adapters } = useSDK();
+  const prefetchedRef = react.useRef(/* @__PURE__ */ new Set());
+  const handleClick = react.useCallback(
+    (item, index) => {
+      if (setFocusOnClick) {
+        setFocusedIndexImmediate(index);
+      }
+      onThumbnailClick?.(item.id, item, index);
+    },
+    [onThumbnailClick, setFocusOnClick, setFocusedIndexImmediate]
+  );
+  const handlePointerEnter = react.useCallback(
+    (item) => {
+      if (!prefetchOnHover) return;
+      if (!isVideoItem(item)) return;
+      if (item.source.type !== "hls") return;
+      if (prefetchedRef.current.has(item.id)) return;
+      const loader = adapters.videoLoader;
+      if (!loader?.preloadMetadata) return;
+      if (loader.isPreloaded(item.id)) {
+        prefetchedRef.current.add(item.id);
+        return;
+      }
+      loader.preloadMetadata(item.source.url);
+      prefetchedRef.current.add(item.id);
+    },
+    [prefetchOnHover, adapters.videoLoader]
+  );
+  const children = react.useMemo(
+    () => items.map((item, index) => {
+      const key = getKey(item, index);
+      const onEnter = prefetchOnHover ? (_e) => handlePointerEnter(item) : void 0;
+      return /* @__PURE__ */ jsxRuntime.jsx(
+        "button",
+        {
+          type: "button",
+          style: buttonResetStyle,
+          "data-thumbnail-index": index,
+          "data-thumbnail-id": item.id,
+          onClick: () => handleClick(item, index),
+          onPointerEnter: onEnter,
+          children: renderThumbnail(item, index)
+        },
+        key
+      );
+    }),
+    [items, getKey, prefetchOnHover, handlePointerEnter, handleClick, renderThumbnail]
+  );
+  if (items.length === 0) {
+    if (loading && renderLoading) return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: renderLoading() });
+    if (error && renderError) {
+      return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: renderError({ message: error.message, retry: refresh }) });
+    }
+    if (!loading && !error && renderEmpty) return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: renderEmpty() });
+    return null;
+  }
+  if (!wrap) return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children });
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { className, children });
+}
 function usePlayerSelector(selector) {
   const { playerEngine } = useSDK();
   const selectorRef = react.useRef(selector);
@@ -3131,6 +3213,7 @@ exports.OptimisticManager = OptimisticManager;
 exports.PlayerEngine = PlayerEngine;
 exports.PlayerStatus = PlayerStatus;
 exports.ReelsFeed = ReelsFeed;
+exports.ReelsFeedThumbnail = ReelsFeedThumbnail;
 exports.ReelsProvider = ReelsProvider;
 exports.ResourceGovernor = ResourceGovernor;
 exports.VALID_TRANSITIONS = VALID_TRANSITIONS;

package/dist/index.d.cts

@@ -875,6 +875,41 @@ interface VideoSlotProps {
 }
 declare function VideoSlot({ item, index, isActive, isPrefetch, isPreloaded, bufferTier, isMuted, onToggleMute, onAutoplayBlocked, showFps, isDragging, renderOverlay, renderActions, renderPauseAction, }: VideoSlotProps): react_jsx_runtime.JSX.Element;
 
+interface ReelsFeedThumbnailProps {
+    /** Render function for a single item's visual card. */
+    renderThumbnail: (videoData: ContentItem, index: number) => ReactNode;
+    /** Click handler — receives the item id, full data, and index in the feed. */
+    onThumbnailClick?: (id: string, videoData: ContentItem, index: number) => void;
+    /** Rendered when the feed is loading and has zero items yet. */
+    renderLoading?: () => ReactNode;
+    /** Rendered when the feed has loaded but is empty. */
+    renderEmpty?: () => ReactNode;
+    /** Rendered when the feed fails with no items — receives a retry callback. */
+    renderError?: (error: {
+        message: string;
+        retry: () => void;
+    }) => ReactNode;
+    /** Outer wrapper className. Defaults to `grid grid-cols-2 gap-3`. */
+    className?: string;
+    /** If the host wants to render its own wrapper, pass `false`. */
+    wrap?: boolean;
+    /**
+     * Update ResourceGovernor's focused index on click so the drawer/feed opens
+     * already pointing at the tapped item.
+     * @default true
+     */
+    setFocusOnClick?: boolean;
+    /**
+     * Prefetch HLS metadata for this slot on `pointerenter`. Off by default;
+     * only useful on hover-capable devices.
+     * @default false
+     */
+    prefetchOnHover?: boolean;
+    /** Key override — useful when host renders multiple lists from the same feed. */
+    getKey?: (item: ContentItem, index: number) => string;
+}
+declare function ReelsFeedThumbnail({ renderThumbnail, onThumbnailClick, renderLoading, renderEmpty, renderError, className, wrap, setFocusOnClick, prefetchOnHover, getKey, }: ReelsFeedThumbnailProps): react_jsx_runtime.JSX.Element | null;
+
 declare function DefaultOverlay({ item }: {
     item: ContentItem;
 }): react_jsx_runtime.JSX.Element;
@@ -1174,4 +1209,4 @@ declare class HttpError extends Error {
     constructor(status: number, message: string, body?: string | undefined);
 }
 
-export { type Article, type ArticleImage, type Author, type BufferTier, type CommentItem, type CommentPage, type ContentItem, type ContentStats, DEFAULT_FEED_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, type FeedConfig, type FeedError, FeedManager, type FeedPage, type FeedState, HttpDataSource, type HttpDataSourceConfig, HttpError, type IAnalytics, type ICommentAdapter, type IDataSource, type IInteraction, type ILogger, type INetworkAdapter, type ISessionStorage, type IVideoLoader, type InteractionState, type LogLevel, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, type NetworkType, OptimisticManager, type PauseSlotActions, type PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PointerGestureConfig, type PreloadResult, type PreloadStatus, ReelsFeed, type ReelsFeedProps, ReelsProvider, type ReelsProviderProps, type ResourceConfig, ResourceGovernor, type ResourceState, type SDKAdapters, type SDKContextValue, type SlotActions, type SnapTarget, type UseHlsOptions, type UseHlsReturn, VALID_TRANSITIONS, type VideoItem, type VideoQuality, VideoSlot, type VideoSource, canPause, canPlay, canSeek, isArticle, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };
+export { type Article, type ArticleImage, type Author, type BufferTier, type CommentItem, type CommentPage, type ContentItem, type ContentStats, DEFAULT_FEED_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, type FeedConfig, type FeedError, FeedManager, type FeedPage, type FeedState, HttpDataSource, type HttpDataSourceConfig, HttpError, type IAnalytics, type ICommentAdapter, type IDataSource, type IInteraction, type ILogger, type INetworkAdapter, type ISessionStorage, type IVideoLoader, type InteractionState, type LogLevel, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, type NetworkType, OptimisticManager, type PauseSlotActions, type PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PointerGestureConfig, type PreloadResult, type PreloadStatus, ReelsFeed, type ReelsFeedProps, ReelsFeedThumbnail, type ReelsFeedThumbnailProps, ReelsProvider, type ReelsProviderProps, type ResourceConfig, ResourceGovernor, type ResourceState, type SDKAdapters, type SDKContextValue, type SlotActions, type SnapTarget, type UseHlsOptions, type UseHlsReturn, VALID_TRANSITIONS, type VideoItem, type VideoQuality, VideoSlot, type VideoSource, canPause, canPlay, canSeek, isArticle, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };

package/dist/index.d.ts

@@ -875,6 +875,41 @@ interface VideoSlotProps {
 }
 declare function VideoSlot({ item, index, isActive, isPrefetch, isPreloaded, bufferTier, isMuted, onToggleMute, onAutoplayBlocked, showFps, isDragging, renderOverlay, renderActions, renderPauseAction, }: VideoSlotProps): react_jsx_runtime.JSX.Element;
 
+interface ReelsFeedThumbnailProps {
+    /** Render function for a single item's visual card. */
+    renderThumbnail: (videoData: ContentItem, index: number) => ReactNode;
+    /** Click handler — receives the item id, full data, and index in the feed. */
+    onThumbnailClick?: (id: string, videoData: ContentItem, index: number) => void;
+    /** Rendered when the feed is loading and has zero items yet. */
+    renderLoading?: () => ReactNode;
+    /** Rendered when the feed has loaded but is empty. */
+    renderEmpty?: () => ReactNode;
+    /** Rendered when the feed fails with no items — receives a retry callback. */
+    renderError?: (error: {
+        message: string;
+        retry: () => void;
+    }) => ReactNode;
+    /** Outer wrapper className. Defaults to `grid grid-cols-2 gap-3`. */
+    className?: string;
+    /** If the host wants to render its own wrapper, pass `false`. */
+    wrap?: boolean;
+    /**
+     * Update ResourceGovernor's focused index on click so the drawer/feed opens
+     * already pointing at the tapped item.
+     * @default true
+     */
+    setFocusOnClick?: boolean;
+    /**
+     * Prefetch HLS metadata for this slot on `pointerenter`. Off by default;
+     * only useful on hover-capable devices.
+     * @default false
+     */
+    prefetchOnHover?: boolean;
+    /** Key override — useful when host renders multiple lists from the same feed. */
+    getKey?: (item: ContentItem, index: number) => string;
+}
+declare function ReelsFeedThumbnail({ renderThumbnail, onThumbnailClick, renderLoading, renderEmpty, renderError, className, wrap, setFocusOnClick, prefetchOnHover, getKey, }: ReelsFeedThumbnailProps): react_jsx_runtime.JSX.Element | null;
+
 declare function DefaultOverlay({ item }: {
     item: ContentItem;
 }): react_jsx_runtime.JSX.Element;
@@ -1174,4 +1209,4 @@ declare class HttpError extends Error {
     constructor(status: number, message: string, body?: string | undefined);
 }
 
-export { type Article, type ArticleImage, type Author, type BufferTier, type CommentItem, type CommentPage, type ContentItem, type ContentStats, DEFAULT_FEED_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, type FeedConfig, type FeedError, FeedManager, type FeedPage, type FeedState, HttpDataSource, type HttpDataSourceConfig, HttpError, type IAnalytics, type ICommentAdapter, type IDataSource, type IInteraction, type ILogger, type INetworkAdapter, type ISessionStorage, type IVideoLoader, type InteractionState, type LogLevel, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, type NetworkType, OptimisticManager, type PauseSlotActions, type PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PointerGestureConfig, type PreloadResult, type PreloadStatus, ReelsFeed, type ReelsFeedProps, ReelsProvider, type ReelsProviderProps, type ResourceConfig, ResourceGovernor, type ResourceState, type SDKAdapters, type SDKContextValue, type SlotActions, type SnapTarget, type UseHlsOptions, type UseHlsReturn, VALID_TRANSITIONS, type VideoItem, type VideoQuality, VideoSlot, type VideoSource, canPause, canPlay, canSeek, isArticle, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };
+export { type Article, type ArticleImage, type Author, type BufferTier, type CommentItem, type CommentPage, type ContentItem, type ContentStats, DEFAULT_FEED_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, type FeedConfig, type FeedError, FeedManager, type FeedPage, type FeedState, HttpDataSource, type HttpDataSourceConfig, HttpError, type IAnalytics, type ICommentAdapter, type IDataSource, type IInteraction, type ILogger, type INetworkAdapter, type ISessionStorage, type IVideoLoader, type InteractionState, type LogLevel, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, type NetworkType, OptimisticManager, type PauseSlotActions, type PlayerConfig, PlayerEngine, type PlayerError, type PlayerEvent, type PlayerEventListener, type PlayerState, PlayerStatus, type PointerGestureConfig, type PreloadResult, type PreloadStatus, ReelsFeed, type ReelsFeedProps, ReelsFeedThumbnail, type ReelsFeedThumbnailProps, ReelsProvider, type ReelsProviderProps, type ResourceConfig, ResourceGovernor, type ResourceState, type SDKAdapters, type SDKContextValue, type SlotActions, type SnapTarget, type UseHlsOptions, type UseHlsReturn, VALID_TRANSITIONS, type VideoItem, type VideoQuality, VideoSlot, type VideoSource, canPause, canPlay, canSeek, isArticle, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };

package/dist/index.js

@@ -2493,6 +2493,88 @@ function parsePxTranslateY(el) {
   if (!match || !match[1]) return 0;
   return Number.parseFloat(match[1]);
 }
+var DEFAULT_CLASSNAME = "grid grid-cols-2 gap-3";
+var defaultGetKey = (item) => item.id;
+var buttonResetStyle = {
+  all: "unset",
+  display: "block",
+  cursor: "pointer",
+  width: "100%",
+  boxSizing: "border-box"
+};
+function ReelsFeedThumbnail({
+  renderThumbnail,
+  onThumbnailClick,
+  renderLoading,
+  renderEmpty,
+  renderError,
+  className = DEFAULT_CLASSNAME,
+  wrap = true,
+  setFocusOnClick = true,
+  prefetchOnHover = false,
+  getKey = defaultGetKey
+}) {
+  const { items, loading, error, refresh } = useFeed();
+  const { setFocusedIndexImmediate } = useResource();
+  const { adapters } = useSDK();
+  const prefetchedRef = useRef(/* @__PURE__ */ new Set());
+  const handleClick = useCallback(
+    (item, index) => {
+      if (setFocusOnClick) {
+        setFocusedIndexImmediate(index);
+      }
+      onThumbnailClick?.(item.id, item, index);
+    },
+    [onThumbnailClick, setFocusOnClick, setFocusedIndexImmediate]
+  );
+  const handlePointerEnter = useCallback(
+    (item) => {
+      if (!prefetchOnHover) return;
+      if (!isVideoItem(item)) return;
+      if (item.source.type !== "hls") return;
+      if (prefetchedRef.current.has(item.id)) return;
+      const loader = adapters.videoLoader;
+      if (!loader?.preloadMetadata) return;
+      if (loader.isPreloaded(item.id)) {
+        prefetchedRef.current.add(item.id);
+        return;
+      }
+      loader.preloadMetadata(item.source.url);
+      prefetchedRef.current.add(item.id);
+    },
+    [prefetchOnHover, adapters.videoLoader]
+  );
+  const children = useMemo(
+    () => items.map((item, index) => {
+      const key = getKey(item, index);
+      const onEnter = prefetchOnHover ? (_e) => handlePointerEnter(item) : void 0;
+      return /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          style: buttonResetStyle,
+          "data-thumbnail-index": index,
+          "data-thumbnail-id": item.id,
+          onClick: () => handleClick(item, index),
+          onPointerEnter: onEnter,
+          children: renderThumbnail(item, index)
+        },
+        key
+      );
+    }),
+    [items, getKey, prefetchOnHover, handlePointerEnter, handleClick, renderThumbnail]
+  );
+  if (items.length === 0) {
+    if (loading && renderLoading) return /* @__PURE__ */ jsx(Fragment, { children: renderLoading() });
+    if (error && renderError) {
+      return /* @__PURE__ */ jsx(Fragment, { children: renderError({ message: error.message, retry: refresh }) });
+    }
+    if (!loading && !error && renderEmpty) return /* @__PURE__ */ jsx(Fragment, { children: renderEmpty() });
+    return null;
+  }
+  if (!wrap) return /* @__PURE__ */ jsx(Fragment, { children });
+  return /* @__PURE__ */ jsx("div", { className, children });
+}
 function usePlayerSelector(selector) {
   const { playerEngine } = useSDK();
   const selectorRef = useRef(selector);
@@ -3103,4 +3185,4 @@ var HttpError = class extends Error {
   }
 };
 
-export { DEFAULT_FEED_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, FeedManager, HttpDataSource, HttpError, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, OptimisticManager, PlayerEngine, PlayerStatus, ReelsFeed, ReelsProvider, ResourceGovernor, VALID_TRANSITIONS, VideoSlot, canPause, canPlay, canSeek, isArticle, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };
+export { DEFAULT_FEED_CONFIG, DEFAULT_PLAYER_CONFIG, DEFAULT_RESOURCE_CONFIG, DefaultActions, DefaultOverlay, DefaultPauseAction, DefaultSkeleton, FeedManager, HttpDataSource, HttpError, MockAnalytics, MockCommentAdapter, MockDataSource, MockInteraction, MockLogger, MockNetworkAdapter, MockSessionStorage, MockVideoLoader, OptimisticManager, PlayerEngine, PlayerStatus, ReelsFeed, ReelsFeedThumbnail, ReelsProvider, ResourceGovernor, VALID_TRANSITIONS, VideoSlot, canPause, canPlay, canSeek, isArticle, isValidTransition, isVideoItem, useFeed, useFeedSelector, useHls, usePlayer, usePlayerSelector, usePointerGesture, useResource, useResourceSelector, useSDK, useSnapAnimation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xhub-reels/sdk",
-  "version": "0.1.22",
+  "version": "0.2.1",
   "description": "High-performance Short Video / Reels SDK for React — optimized for Flutter WebView",
   "license": "MIT",
   "type": "module",