@revenuecat/purchases-ui-js 4.1.0 → 4.2.0

package/dist/components/carousel/Carousel.stories.svelte

@@ -4,6 +4,7 @@
   import { viewportDecorator } from "../../stories/viewport-decorator";
   import type { CarouselProps } from "../../types/components/carousel";
   import { DEFAULT_SPACING } from "../../utils/constants";
+  import { STORY_BACKGROUND_VIDEO_FILL } from "../../stories/video-background-story-fixture";
   import { defineMeta } from "@storybook/addon-svelte-csf";
   import Carousel from "./Carousel.svelte";
 
@@ -442,6 +443,34 @@
   });
 </script>
 
+<Story
+  name="Surface — video background (stacking / z-order)"
+  parameters={{
+    chromatic: { disableSnapshot: true },
+    docs: {
+      description: {
+        story:
+          "**Z-order:** video layer → tinted `::before` → carousel clip (slides + controls). Rounded corners should clip the backdrop; Chromatic skips motion snapshots.",
+      },
+    },
+  }}
+  args={{
+    background: STORY_BACKGROUND_VIDEO_FILL,
+    shape: {
+      type: "rectangle",
+      corners: {
+        bottom_leading: 20,
+        bottom_trailing: 20,
+        top_leading: 20,
+        top_trailing: 20,
+      },
+    },
+    auto_advance: null,
+    loop: false,
+    initial_page_index: 0,
+  }}
+/>
+
 <Story
   name="No loop - first page"
   args={{

package/dist/components/carousel/Carousel.svelte

@@ -2,8 +2,16 @@
   import { getColorModeContext } from "../../stores/color-mode";
   import { getPaywallContext } from "../../stores/paywall";
   import { getSelectedStateContext } from "../../stores/selected";
+  import BackgroundVideoSurface from "../paywall/BackgroundVideoSurface.svelte";
   import type { CarouselProps } from "../../types/components/carousel";
-  import { mapBackground } from "../../utils/background-utils";
+  import {
+    mapBackground,
+    resolveBackgroundVideoForSurface,
+  } from "../../utils/background-utils";
+  import {
+    rcVideoBackgroundHostClass,
+    videoBackgroundHostStyles,
+  } from "../../utils/video-background-host";
   import {
     css,
     mapBorder,
@@ -33,7 +41,7 @@
     page_peek,
     page_control,
     initial_page_index,
-    loop,
+    loop: carouselPagingLoop,
     auto_advance,
   } = $derived.by(() => {
     return {
@@ -46,13 +54,26 @@
   const colorMode = $derived(getColorMode());
   const { emitComponentInteraction } = getPaywallContext();
 
+  const hasVideoBg = $derived(background?.type === "video");
+  const videoSurface = $derived.by(() => {
+    if (!hasVideoBg) return null;
+    const bg = background;
+    if (!bg || bg.type !== "video") return null;
+    return resolveBackgroundVideoForSurface(colorMode, bg);
+  });
+  const borderRadiusCssForBg = $derived(mapBorderRadius(shape));
+
   const carouselStyle = $derived(
     css({
       margin: mapSpacing(margin),
       padding: mapSpacing(padding),
+      ...videoBackgroundHostStyles({
+        hasVideoBg,
+        positionRelative: true,
+      }),
       ...mapBackground(colorMode, null, background),
       ...mapBorder(colorMode, border),
-      "border-radius": mapBorderRadius(shape),
+      "border-radius": borderRadiusCssForBg,
       "box-shadow": mapShadow(colorMode, shadow),
       "transition-duration": `${auto_advance?.ms_transition_time ?? 0}ms`,
     }),
@@ -67,7 +88,7 @@
   );
 
   const prevPages = $derived.by(() => {
-    if (!loop) {
+    if (!carouselPagingLoop) {
       return [];
     }
 
@@ -85,7 +106,7 @@
   });
 
   const nextPages = $derived.by(() => {
-    if (!loop) {
+    if (!carouselPagingLoop) {
       return [];
     }
 
@@ -138,7 +159,7 @@
     }
   }
 
-  const loopOffset = $derived(loop ? 2 : 0);
+  const loopOffset = $derived(carouselPagingLoop ? 2 : 0);
 
   function setSliderTranslate(translate: number) {
     if (slider !== null) {
@@ -238,7 +259,7 @@
       return;
     }
 
-    const [min, max] = loop
+    const [min, max] = carouselPagingLoop
       ? [startTranslation - carouselWidth, startTranslation + carouselWidth]
       : [-(pages.length - 1) * pageWidth, 0];
     const translation = getTranslation(slider);
@@ -252,7 +273,29 @@
   }
 </script>
 
-<div class="carousel rc-gradient-border" style={carouselStyle}>
+<div
+  class={[
+    "carousel",
+    "rc-gradient-border",
+    hasVideoBg ? rcVideoBackgroundHostClass("carousel") : "",
+  ]
+    .filter(Boolean)
+    .join(" ")}
+  style={carouselStyle}
+>
+  {#if videoSurface}
+    <div class="carousel-bg-video-mount">
+      <BackgroundVideoSurface
+        url={videoSurface.url}
+        urlLowRes={videoSurface.url_low_res}
+        objectFit={videoSurface.fit}
+        objectPosition={videoSurface.position}
+        poster={videoSurface.posterWebp}
+        mute={videoSurface.mute}
+        loop={videoSurface.loop}
+      />
+    </div>
+  {/if}
   <div class="carousel-clip">
     <div
       bind:this={slider}
@@ -324,6 +367,29 @@
     border-radius: inherit;
   }
 
+  .carousel-bg-video-mount {
+    position: absolute;
+    inset: 0;
+    z-index: 1;
+    border-radius: inherit;
+    overflow: hidden;
+    pointer-events: none;
+  }
+
+  .carousel.rc-carousel-video-bg::before {
+    content: "";
+    position: absolute;
+    inset: 0;
+    background: var(--overlay);
+    pointer-events: none;
+    z-index: 2;
+  }
+
+  .carousel.rc-carousel-video-bg .carousel-clip {
+    position: relative;
+    z-index: 3;
+  }
+
   .slider {
     display: flex;
     flex-direction: row;

package/dist/components/paywall/BackgroundVideoSurface.svelte

@@ -0,0 +1,162 @@
+<script lang="ts">
+  import { onMount, untrack } from "svelte";
+  import { subscribeCompatMediaChange } from "../../utils/match-media-compat";
+  import {
+    subscribeDecorativeVideoAutoplayAttempts,
+    tryDecorativeAutoplayWithMuteFallback,
+  } from "../../utils/video-inline-playback";
+
+  interface Props {
+    url: string;
+    urlLowRes?: string | null;
+    objectFit: string;
+    objectPosition: string;
+    poster?: string | null;
+    mute: boolean;
+    loop: boolean;
+  }
+
+  let {
+    url,
+    urlLowRes = null,
+    objectFit,
+    objectPosition,
+    poster = null,
+    mute,
+    loop,
+  }: Props = $props();
+
+  let videoElement = $state<HTMLVideoElement | null>(null);
+  let hasError = $state(false);
+  let reduceMotion = $state(false);
+  /** When unmuted autoplay fails, retry muted (Safari autoplay policy). */
+  let playbackMutedOverride = $state(false);
+
+  onMount(() => {
+    if (typeof window === "undefined") return;
+    const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+    reduceMotion = mq.matches;
+    const onChange = () => {
+      reduceMotion = mq.matches;
+    };
+    return subscribeCompatMediaChange(mq, onChange);
+  });
+
+  $effect(() => {
+    url;
+    urlLowRes;
+    untrack(() => {
+      hasError = false;
+      playbackMutedOverride = false;
+    });
+    queueMicrotask(() => {
+      videoElement?.load();
+    });
+  });
+
+  const showPosterOnly = $derived(reduceMotion || hasError);
+
+  const mediaStyle = $derived(
+    `object-fit:${objectFit};object-position:${objectPosition}`,
+  );
+
+  $effect(() => {
+    if (showPosterOnly || !videoElement) {
+      untrack(() => {
+        playbackMutedOverride = false;
+      });
+      return;
+    }
+
+    const el = videoElement;
+    let cancelled = false;
+    const isCancelled = () => cancelled;
+
+    const tryPlay = () => {
+      tryDecorativeAutoplayWithMuteFallback(el, {
+        cancelled: isCancelled,
+        preferMuted: mute,
+        getMutedOverride: () => playbackMutedOverride,
+        setMutedOverride: (v) =>
+          untrack(() => {
+            playbackMutedOverride = v;
+          }),
+      });
+    };
+
+    const removeMediaListeners = subscribeDecorativeVideoAutoplayAttempts(
+      el,
+      tryPlay,
+      isCancelled,
+    );
+
+    return () => {
+      cancelled = true;
+      removeMediaListeners();
+    };
+  });
+
+  function onVideoError() {
+    hasError = true;
+  }
+</script>
+
+{#if showPosterOnly && poster}
+  <div class="rc-bg-video" aria-hidden="true">
+    <img src={poster} alt="" class="fill" style={mediaStyle} />
+  </div>
+{:else if showPosterOnly}
+  <!-- No poster/fallback asset for reduced motion or failed load -->
+{:else}
+  <!-- svelte-ignore a11y_media_has_caption decorative background -->
+  <div class="rc-bg-video" aria-hidden="true">
+    <video
+      bind:this={videoElement}
+      class="fill"
+      style={mediaStyle}
+      {loop}
+      muted={mute || playbackMutedOverride}
+      playsinline
+      autoplay
+      preload="auto"
+      poster={poster ?? undefined}
+      onerror={onVideoError}
+    >
+      {#if urlLowRes}
+        <!-- Narrow viewports use low-res asset first; larger screens use primary URL. -->
+        <source src={urlLowRes} media="(max-width: 600px)" />
+      {/if}
+      <source src={url} />
+    </video>
+  </div>
+{/if}
+
+<style>
+  .rc-bg-video {
+    position: absolute;
+    inset: 0;
+    overflow: hidden;
+    z-index: 1;
+    pointer-events: none;
+  }
+
+  /**
+   * Fill the layer with absolute edges (percent heights are unreliable under nested
+   * flex/absolute hosts). Beat Paywall's global `.paywall video { max-width: 100% }`
+   * so `object-fit: cover|contain` applies to the full backdrop box (e.g. carousel).
+   */
+  .rc-bg-video :is(video, img).fill {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    max-width: none;
+    max-height: none;
+    display: block;
+  }
+
+  .rc-bg-video video.fill {
+    transform: translateZ(0);
+    -webkit-transform: translateZ(0);
+  }
+</style>

package/dist/components/paywall/BackgroundVideoSurface.svelte.d.ts

@@ -0,0 +1,12 @@
+interface Props {
+    url: string;
+    urlLowRes?: string | null;
+    objectFit: string;
+    objectPosition: string;
+    poster?: string | null;
+    mute: boolean;
+    loop: boolean;
+}
+declare const BackgroundVideoSurface: import("svelte").Component<Props, {}, "">;
+type BackgroundVideoSurface = ReturnType<typeof BackgroundVideoSurface>;
+export default BackgroundVideoSurface;

package/dist/components/paywall/Paywall.stories.svelte

@@ -27,6 +27,7 @@
   import { BACKGROUND_PAYWALL } from "./fixtures/background-paywall";
   import { OVERRIDE_PAYWALL } from "./fixtures/override-paywall";
   import { SHEET_PAYWALL } from "./fixtures/sheet-paywall";
+  import { SHEET_PAYWALL_VIDEO_STACKING } from "./fixtures/sheet-video-stacking-paywall";
   import { STACK_PAYWALL } from "./fixtures/stack-paywall";
   import { VARIABLES } from "./fixtures/variables";
   import { CUSTOM_VARIABLES_PAYWALL } from "./fixtures/custom-variables-paywall";
@@ -93,6 +94,28 @@
   }}
 />
 
+<Story
+  name="Sheet — video background (stacking / z-order)"
+  parameters={{
+    chromatic: { disableSnapshot: true },
+    docs: {
+      description: {
+        story:
+          "**Z-order:** `BackgroundVideoSurface` under the sheet panel (`z-index: 1`), CSS `::before` tint (`z-index: 2`), inner `Stack` (`z-index: 3`). Backdrop dim is outside the sheet chrome. Motion is disabled in Chromatic.",
+      },
+    },
+  }}
+  decorators={[viewportDecorator(500, 500, 0)]}
+  play={async ({ canvasElement }) => {
+    const button = canvasElement.querySelector("button");
+    button?.click();
+    await waitForAnimations();
+  }}
+  args={{
+    paywallData: SHEET_PAYWALL_VIDEO_STACKING,
+  }}
+/>
+
 <Story
   name="Background - Color"
   decorators={[viewportDecorator(500, 500, 0)]}
@@ -231,6 +254,116 @@
   }}
 />
 
+<Story
+  name="Background - Video fill"
+  decorators={[viewportDecorator(500, 500, 0)]}
+  parameters={{ chromatic: { disableSnapshot: true } }}
+  args={{
+    paywallData: BACKGROUND_PAYWALL({
+      type: "video",
+      fit_mode: "fill",
+      mute_audio: true,
+      loop: true,
+      color_overlay: null,
+      fallback_image: {
+        light: {
+          width: 640,
+          height: 360,
+          original:
+            "https://placehold.co/640x360/1a1a2e/ffffff.webp?text=Poster",
+          heic: "https://placehold.co/640x360/1a1a2e/ffffff.webp?text=Poster",
+          heic_low_res:
+            "https://placehold.co/640x360/1a1a2e/ffffff.webp?text=Poster",
+          webp: "https://placehold.co/640x360/1a1a2e/ffffff.webp?text=Poster",
+          webp_low_res:
+            "https://placehold.co/640x360/1a1a2e/ffffff.webp?text=Poster",
+        },
+      },
+      value: {
+        light: {
+          width: 1920,
+          height: 1080,
+          url: "https://videos.pexels.com/video-files/10288594/10288594-hd_1920_1080_25fps.mp4",
+          url_low_res:
+            "https://videos.pexels.com/video-files/10288594/10288594-hd_1920_1080_25fps.mp4",
+        },
+      },
+    }),
+  }}
+/>
+
+<Story
+  name="Background - Video fit"
+  decorators={[viewportDecorator(500, 500, 0)]}
+  parameters={{ chromatic: { disableSnapshot: true } }}
+  args={{
+    paywallData: BACKGROUND_PAYWALL({
+      type: "video",
+      fit_mode: "fit",
+      mute_audio: true,
+      loop: true,
+      color_overlay: null,
+      fallback_image: null,
+      value: {
+        light: {
+          width: 1920,
+          height: 1080,
+          url: "https://videos.pexels.com/video-files/10288594/10288594-hd_1920_1080_25fps.mp4",
+          url_low_res:
+            "https://videos.pexels.com/video-files/10288594/10288594-hd_1920_1080_25fps.mp4",
+        },
+      },
+    }),
+  }}
+/>
+
+<Story
+  name="Background - Video with tint overlay"
+  decorators={[viewportDecorator(500, 500, 0)]}
+  parameters={{ chromatic: { disableSnapshot: true } }}
+  args={{
+    paywallData: BACKGROUND_PAYWALL({
+      type: "video",
+      fit_mode: "fill",
+      mute_audio: true,
+      loop: true,
+      color_overlay: {
+        light: {
+          type: "linear",
+          degrees: 180,
+          points: [
+            { percent: 0, color: "#00000066" },
+            { percent: 100, color: "#1a0a3080" },
+          ],
+        },
+      },
+      fallback_image: {
+        light: {
+          width: 640,
+          height: 360,
+          original:
+            "https://placehold.co/640x360/2d1b4e/ffffff.webp?text=Poster",
+          heic: "https://placehold.co/640x360/2d1b4e/ffffff.webp?text=Poster",
+          heic_low_res:
+            "https://placehold.co/640x360/2d1b4e/ffffff.webp?text=Poster",
+          webp: "https://placehold.co/640x360/2d1b4e/ffffff.webp?text=Poster",
+          webp_low_res:
+            "https://placehold.co/640x360/2d1b4e/ffffff.webp?text=Poster",
+        },
+      },
+      value: {
+        light: {
+          width: 1920,
+          height: 1080,
+          url: "https://videos.pexels.com/video-files/10288594/10288594-hd_1920_1080_25fps.mp4",
+          url_low_res:
+            "https://videos.pexels.com/video-files/10288594/10288594-hd_1920_1080_25fps.mp4",
+        },
+      },
+    }),
+  }}
+/>
+
 <Story
   name="Primary"
   args={{

package/dist/components/paywall/Sheet.svelte

@@ -2,8 +2,16 @@
   import { getColorModeContext } from "../../stores/color-mode";
   import { getPaywallContext } from "../../stores/paywall";
   import { getSelectedStateContext } from "../../stores/selected";
+  import BackgroundVideoSurface from "./BackgroundVideoSurface.svelte";
   import type { SheetProps } from "../../types/components/sheet";
-  import { mapBackground } from "../../utils/background-utils";
+  import {
+    mapBackground,
+    resolveBackgroundVideoForSurface,
+  } from "../../utils/background-utils";
+  import {
+    rcVideoBackgroundHostClass,
+    videoBackgroundHostStyles,
+  } from "../../utils/video-background-host";
   import { css, mapSize } from "../../utils/base-utils";
   import { getActiveStateProps } from "../../utils/style-utils";
   import { onMount } from "svelte";
@@ -23,6 +31,14 @@
   const getColorMode = getColorModeContext();
   const colorMode = $derived(getColorMode());
 
+  const hasVideoBg = $derived(background?.type === "video");
+  const videoSurface = $derived.by(() => {
+    if (!hasVideoBg) return null;
+    const bg = background;
+    if (!bg || bg.type !== "video") return null;
+    return resolveBackgroundVideoForSurface(colorMode, bg);
+  });
+
   const backdropStyle = $derived(
     css({
       background: background_blur ? "#0000003f" : "",
@@ -32,6 +48,10 @@
   const sheetStyle = $derived(
     css({
       height: mapSize(size.height),
+      ...videoBackgroundHostStyles({
+        hasVideoBg,
+        clipOverflow: true,
+      }),
       ...mapBackground(colorMode, null, background),
     }),
   );
@@ -75,7 +95,14 @@
     }
   };
 
-  let sheetClass = $derived(`sheet ${visible ? "visible" : ""}`);
+  let sheetClass = $derived(
+    [
+      `sheet ${visible ? "visible" : ""}`,
+      hasVideoBg ? rcVideoBackgroundHostClass("sheet") : "",
+    ]
+      .filter(Boolean)
+      .join(" "),
+  );
 </script>
 
 <div
@@ -95,7 +122,21 @@
     aria-modal="true"
     {ontransitionend}
   >
-    <Stack {...stack} />
+    {#if videoSurface}
+      <BackgroundVideoSurface
+        url={videoSurface.url}
+        urlLowRes={videoSurface.url_low_res}
+        objectFit={videoSurface.fit}
+        objectPosition={videoSurface.position}
+        poster={videoSurface.posterWebp}
+        mute={videoSurface.mute}
+        loop={videoSurface.loop}
+      />
+    {/if}
+    <Stack
+      {...stack}
+      class={hasVideoBg ? "rc-sheet-stack-above-video" : undefined}
+    />
   </div>
 </div>
 
@@ -119,8 +160,30 @@
     transition-timing-function: cubic-bezier(0, 0, 0.2, 1);
     transform: translateY(100%);
 
+    &::before {
+      content: "";
+      position: absolute;
+      inset: 0;
+      background: var(--overlay);
+      pointer-events: none;
+    }
+
     &.visible {
       transform: translateY(0);
     }
   }
+
+  .sheet.rc-sheet-video-bg::before {
+    z-index: 2;
+  }
+
+  /* Match stack video stacking: tint above video (::before z-index). */
+  .sheet.rc-sheet-video-bg > :global(.rc-bg-video) {
+    z-index: 1;
+  }
+
+  .sheet.rc-sheet-video-bg > :global(.rc-sheet-stack-above-video) {
+    position: relative;
+    z-index: 3;
+  }
 </style>

package/dist/components/paywall/ViewportBackdrop.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import type { PaywallRootBackgroundModel } from "../../utils/background-utils";
+  import BackgroundVideoSurface from "./BackgroundVideoSurface.svelte";
 
   // iOS WebKit only reliably propagates background-color (not background-image)
   // through to the safe-area canvas. A position:fixed element that explicitly
@@ -27,19 +28,43 @@
     return "";
   });
 
-  const overlayStyle = $derived(
-    model.kind === "image" && model.overlay && model.overlay !== "none"
-      ? `background:${model.overlay}`
-      : null,
-  );
+  const overlayStyle = $derived.by((): string | null => {
+    if (model.kind !== "image" && model.kind !== "video") {
+      return null;
+    }
+    if (!model.overlay || model.overlay === "none") {
+      return null;
+    }
+    return `background:${model.overlay}`;
+  });
 
-  const shouldRender = $derived(backdropStyle !== "");
+  const shouldRenderBackdrop = $derived(
+    backdropStyle !== "" || model.kind === "video",
+  );
 </script>
 
-{#if shouldRender}
-  <div class="viewport-backdrop" style={backdropStyle}>
+{#if shouldRenderBackdrop}
+  <div
+    class="viewport-backdrop"
+    style={backdropStyle !== "" ? backdropStyle : undefined}
+  >
+    {#if model.kind === "video"}
+      <BackgroundVideoSurface
+        url={model.url}
+        urlLowRes={model.url_low_res}
+        objectFit={model.fit}
+        objectPosition={model.position}
+        poster={model.posterWebp}
+        mute={model.mute}
+        loop={model.loop}
+      />
+    {/if}
     {#if overlayStyle}
-      <div class="viewport-backdrop-overlay" style={overlayStyle}></div>
+      <div
+        class="viewport-backdrop-overlay"
+        class:z-over-video-bg={model.kind === "video"}
+        style={overlayStyle}
+      ></div>
     {/if}
   </div>
 {/if}
@@ -51,11 +76,17 @@
     z-index: 0;
     pointer-events: none;
     overflow: hidden;
+    isolation: isolate;
   }
 
   .viewport-backdrop-overlay {
     position: absolute;
     inset: 0;
     pointer-events: none;
+    z-index: 1;
+  }
+
+  .viewport-backdrop-overlay.z-over-video-bg {
+    z-index: 2;
   }
 </style>