@shortkitsdk/react-native 0.2.31 → 0.2.33

package/src/types.ts

@@ -52,6 +52,35 @@ export type VideoCarouselOverlayConfig =
   | 'none'
   | { type: 'custom'; name: string; component: React.ComponentType<VideoCarouselOverlayProps> };
 
+/**
+ * Custom feed mask config for `<ShortKitPlayer>` / `<ShortKitWidget>`.
+ *
+ * When set to `{type: 'custom', name, component}`, the SDK presents the
+ * expanded feed embedded inside the host-supplied React component rather
+ * than full-screen. The mask renders chrome (e.g. a footer pill) AROUND
+ * the feed; the feed itself occupies the `<ShortKitFeedRegion>` placeholder
+ * the host puts somewhere in the mask's tree.
+ *
+ * iOS only. On Android the prop is currently a no-op.
+ */
+export type FeedMaskConfig =
+  | 'none'
+  | { type: 'custom'; name: string; component: React.ComponentType<FeedMaskProps> };
+
+/**
+ * Props passed to the host-supplied feed mask component as the user pages
+ * through the expanded feed. Mirrors a subset of `OverlayProps` —
+ * additional fields (playback state, time, etc.) can be added later.
+ */
+export interface FeedMaskProps {
+  /** The currently-active feed item. Re-renders the mask when paging. */
+  item: ContentItem;
+  /** Active item's index in the feed, when known. */
+  activeIndex?: number;
+  /** Total feed length, when known (paginated feeds may grow). */
+  totalCount?: number;
+}
+
 // --- Data Models ---
 
 export interface ContentItem {
@@ -73,6 +102,10 @@ export interface ContentItem {
 
 export type DownloadStatus = 'idle' | 'downloading' | 'completed' | 'failed';
 
+export type DownloadOverlayMode = 'none' | 'static' | 'deterministic';
+
+export type DownloadPhase = 'downloading' | 'compositing' | 'finalizing';
+
 export interface DownloadState {
   status: DownloadStatus;
   /** ID of the content item being downloaded, if any. */
@@ -434,6 +467,12 @@ export interface PlayerConfig {
   muteOnStart?: boolean;
   overlay?: OverlayConfig;
   feedConfig?: FeedConfig;
+  /**
+   * Optional feed mask. When `{type: 'custom', ...}`, the SDK embeds the
+   * expanded feed inside the host's React component instead of presenting
+   * full-screen. iOS only. See `FeedMaskConfig` for full semantics.
+   */
+  feedMask?: FeedMaskConfig;
 }
 
 // --- Widget Config ---
@@ -450,6 +489,24 @@ export interface WidgetConfig {
   overlay?: OverlayConfig;
   filter?: FeedFilter;
   feedConfig?: FeedConfig;
+  /**
+   * Optional feed mask, same shape as `PlayerConfig.feedMask`. iOS only.
+   */
+  feedMask?: FeedMaskConfig;
+  /**
+   * How the widget schedules preview playback across cells.
+   * - `'singleVisibleRotating'` (default): one visible card plays at a
+   *   time using an HLS Instant Clip; advances to the next visible card
+   *   on natural EOS, wrapping at the end. Off-screen cards never play.
+   * - `'allVisibleSimultaneous'`: every visible card plays simultaneously,
+   *   hard-capped at 3. Each card loops its own preview in place.
+   */
+  playbackMode?: 'singleVisibleRotating' | 'allVisibleSimultaneous';
+  /**
+   * Length of the looping preview window in seconds. Used to construct the
+   * Mux Instant Clip URL for each card. Defaults to 5.
+   */
+  previewDuration?: number;
 }
 
 /**
@@ -469,6 +526,22 @@ export interface ShortKitPlayerProps {
    *  returns to thumbnail-only mode without tearing down the view. Defaults to
    *  the value of `config.autoplay` (which itself defaults to `true`). */
   active?: boolean;
+  /**
+   * Optional list of items used to seed the expanded feed when the user
+   * taps the player and `config.clickAction === 'feed'`. The inline
+   * player's own `contentItem` is automatically prepended (deduped by
+   * playback ID), so the modal-zoom transition lands on the inline
+   * clip and the host's items follow.
+   *
+   * Combine with `config.feedConfig.feedSource`:
+   *   - `'algorithmic'` (default) → expanded feed plays the seeded
+   *     items, then continues paginating via `/v1/feed`.
+   *   - `'custom'` → expanded feed plays only the seeded items and
+   *     stops at the end (closed list).
+   *
+   * Has no effect when `clickAction !== 'feed'`.
+   */
+  feedItems?: FeedInput[];
   style?: ViewStyle;
   onTap?: () => void;
 }
@@ -495,6 +568,32 @@ export interface ShortKitWidgetProps {
    * regardless (per-cell mute toggle runs alongside `onCardTap`).
    */
   onCardTap?: (playbackId: string, index: number) => void;
+  /**
+   * Whether the widget is currently allowed to play. Defaults to `true`.
+   * When `false`, the widget stops its rotation timer and deactivates
+   * whichever card was active — releasing its tile back to the SDK
+   * player pool. Use this for viewport-aware playback orchestration
+   * (e.g. tab-focus gating: `active={isFocused}`). Mirrors
+   * `<ShortKitFeed>`'s same-named prop.
+   */
+  active?: boolean;
+  /**
+   * Optional list of items used to seed the expanded feed when the user
+   * taps a card and `config.clickAction === 'feed'`. The widget's own
+   * `items` (the carousel cards) are automatically prepended (deduped
+   * by playback ID), so the modal-zoom transition lands on the tapped
+   * clip and the host's items follow.
+   *
+   * Combine with `config.feedConfig.feedSource`:
+   *   - `'algorithmic'` (default) → expanded feed plays the seeded
+   *     items, then continues paginating via `/v1/feed`.
+   *   - `'custom'` → expanded feed plays only the seeded items and
+   *     stops at the end (closed list).
+   *
+   * Has no effect when `clickAction !== 'feed'`. Mirrors the
+   * `feedItems` prop on `<ShortKitPlayer>`.
+   */
+  feedItems?: FeedInput[];
   style?: ViewStyle;
 }