@revenuecat/purchases-ui-js 4.0.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

@@ -3,7 +3,6 @@
   import type { ComponentProps } from "svelte";
 
   import Paywall from "./Paywall.svelte";
-  import Main from "../layout/Main/Main.svelte";
   import {
     alignmentPaywallData,
     calmPaywallData,
@@ -28,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";
@@ -63,9 +63,7 @@
 
 {#snippet template(props: ComponentProps<typeof Paywall>)}
   <div class="paywall-story-frame">
-    <Main paywallData={props.paywallData}>
-      <Paywall {...props} />
-    </Main>
+    <Paywall {...props} />
   </div>
 {/snippet}
 
@@ -96,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)]}
@@ -234,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={{
@@ -510,10 +640,4 @@
     background-color: var(--rc-purchases-ui-bg-color, Canvas);
     color-scheme: light dark;
   }
-
-  /* Allow chromatic to capture the full content snapshot */
-  .paywall-story-frame :global(.paywall-content-scroll) {
-    flex: 1 1 auto;
-    overflow-y: visible;
-  }
 </style>

package/dist/components/paywall/Paywall.svelte

@@ -32,13 +32,17 @@
     type PackageInfo,
     type VariableDictionary,
   } from "../../types/variables";
+  import { paywallRootBackgroundModel } from "../../utils/background-utils";
+  import { css } from "../../utils/base-utils";
   import { STICKY_OVERLAY_Z_INDEX } from "../../utils/constants";
+  import { applyDocumentBackground } from "../../utils/document-background";
   import { registerFonts } from "../../utils/font-utils";
   import { findSelectedPackageId } from "../../utils/style-utils";
   import { onMount } from "svelte";
   import { derived, readable, writable } from "svelte/store";
   import Stack from "../stack/Stack.svelte";
   import Sheet from "./Sheet.svelte";
+  import ViewportBackdrop from "./ViewportBackdrop.svelte";
   import {
     type PackageInfoStore,
     setPackageInfoContext,
@@ -128,13 +132,39 @@
     customVariables = {},
   }: Props = $props();
 
-  setColorModeContext(() => preferredColorMode);
+  const getColorMode = setColorModeContext(() => preferredColorMode);
+
+  const viewportBackdropModel = $derived(
+    paywallRootBackgroundModel(paywallData, getColorMode()),
+  );
+
+  const instanceId: symbol = Symbol();
+  $effect(() =>
+    applyDocumentBackground(instanceId, viewportBackdropModel, paywallData),
+  );
 
   const { default_locale, components_config, components_localizations } =
     paywallData;
   const { base } = components_config;
   const defaultPackageId = findSelectedPackageId(base);
 
+  // Solid colours paint here so the paywall has its own bg without requiring
+  // consumer CSS. Gradients and images are deliberately skipped — ViewportBackdrop
+  // paints those at viewport scale, and rendering them on both surfaces would
+  // anchor the gradient stops to two different boxes and produce a visible seam
+  // at the paywall edge.
+  const paywallStyle = $derived.by((): string => {
+    const m = viewportBackdropModel;
+    if (
+      m.kind === "style" &&
+      m.style.background &&
+      !m.style.background.includes("gradient")
+    ) {
+      return css(m.style);
+    }
+    return "";
+  });
+
   const { getLocalizedString } = setLocalizationContext(() => ({
     defaultLocale: default_locale,
     selectedLocale,
@@ -300,7 +330,8 @@
 </script>
 
 <svelte:boundary onerror={onError}>
-  <div class={paywallClass}>
+  <div class={paywallClass} style={paywallStyle}>
+    <ViewportBackdrop model={viewportBackdropModel} />
     {#if header}
       <div
         class="header-wrapper"
@@ -345,10 +376,9 @@
   .paywall {
     position: relative;
     display: flex;
-    flex: 1 1 auto;
     flex-direction: column;
     align-items: stretch;
-    min-height: 0;
+    height: 100%;
 
     transition-property: filter, transform;
     transition-duration: 0.1s;
@@ -370,13 +400,13 @@
   .paywall-content {
     z-index: 2;
     width: 100%;
-    flex: 1;
+    flex: 1 1 auto;
     display: flex;
     flex-direction: column;
     min-height: 0;
 
     & > :global(.paywall-content-scroll) {
-      flex: 1 1 0;
+      flex: 1 1 auto;
       min-height: 0;
       overflow-y: auto;
     }